@cosmicjs/sdk
Version:
The official client module for Cosmic. This module helps you easily add dynamic content to your website or application using the Cosmic headless CMS.
423 lines (335 loc) • 12.6 kB
Markdown
# AI Video Generation with Cosmic SDK
Generate AI-powered videos using Google's Veo 3.1 models directly from your JavaScript/TypeScript applications.
## Installation
```bash
npm install @cosmicjs/sdk
```
## Quick Start
```typescript
import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: 'YOUR_BUCKET_SLUG',
readKey: 'YOUR_READ_KEY',
writeKey: 'YOUR_WRITE_KEY'
})
// Generate a video
const video = await cosmic.ai.generateVideo({
prompt: 'A calico kitten playing with a ball of yarn in golden sunlight',
duration: 8,
resolution: '720p'
})
console.log(video.media.url) // Direct CDN URL to the video
```
## API Reference
### `generateVideo(options)`
Generate AI videos using Google's Veo 3.1 models.
#### Parameters
```typescript
interface GenerateVideoOptions {
prompt: string; // Required
model?: 'veo-3.1-fast-generate-preview' // Optional (default: fast)
| 'veo-3.1-generate-preview';
duration?: 4 | 6 | 8; // Optional (default: 8)
resolution?: '720p' | '1080p'; // Optional (default: '720p')
reference_images?: string[]; // Optional (max 3 URLs)
metadata?: Record<string, any>; // Optional
folder?: string; // Optional
}
```
#### Response
```typescript
interface VideoGenerationResponse {
media: {
id: string;
name: string;
url: string; // Direct CDN URL
imgix_url: string;
type: string; // 'video/mp4'
size: number; // File size in bytes
bucket: string;
created_at: string;
metadata?: {
duration: number; // Video duration in seconds
resolution: string; // '720p' or '1080p'
generation_time_seconds: number;
prompt?: string; // Original prompt
model?: string; // Model used
[key: string]: any; // Custom metadata
};
folder?: string | null;
alt_text?: string;
};
usage: {
input_tokens: number; // Prompt tokens (typically 0)
output_tokens: number; // Video generation cost (144K-768K)
total_tokens: number;
};
generation_time_seconds: number; // Total generation time
}
```
### `extendVideo(options)`
Extend a previously generated Veo video by creating a new 8-second clip that continues from the final second of the original video.
#### Parameters
```typescript
interface ExtendVideoOptions {
prompt: string; // Required - how to continue the video
media_id: string; // Required - ID of the Veo video to extend
model?: 'veo-3.1-fast-generate-preview' // Optional (default: fast)
| 'veo-3.1-generate-preview';
metadata?: Record<string, any>; // Optional
folder?: string; // Optional
}
```
#### Response
```typescript
interface VideoExtensionResponse {
media: {
id: string;
name: string;
url: string; // Direct CDN URL
imgix_url: string;
type: string; // 'video/mp4'
size: number;
bucket: string;
created_at: string;
metadata?: {
duration: number; // Always 8 seconds for extensions
resolution: string; // Always '720p' for extensions
generation_time_seconds: number;
is_extension: boolean; // true
source_media_id: string; // ID of the original video
veo_file_uri: string; // URI for further extensions
[key: string]: any;
};
folder?: string | null;
alt_text?: string;
};
usage: {
input_tokens: number;
output_tokens: number; // 288,000 (Fast) or 768,000 (Standard)
total_tokens: number;
};
generation_time_seconds: number;
source_media_id: string; // ID of the original video
is_extension: boolean; // true
}
```
#### Video Extension Limitations
- **Duration**: Extensions are always 8 seconds
- **Resolution**: Extensions are always 720p (even if the original was 1080p)
- **Source**: Only Veo-generated videos can be extended (must have `veo_file_uri` in metadata)
- **Chaining**: Extended videos can also be extended, enabling creation of longer narratives
## Examples
### Basic Video Generation
```typescript
const video = await cosmic.ai.generateVideo({
prompt: 'A serene mountain landscape at sunset with gentle wind rustling through trees',
duration: 6,
resolution: '720p'
})
console.log(`Video URL: ${video.media.url}`)
console.log(`Duration: ${video.media.metadata.duration}s`)
console.log(`Tokens used: ${video.usage.total_tokens}`)
```
### Premium Quality Video
```typescript
const premiumVideo = await cosmic.ai.generateVideo({
prompt: 'Cinematic close-up of raindrops falling on a window at night, city lights blurred in the background',
model: 'veo-3.1-generate-preview', // Premium quality
duration: 8,
resolution: '1080p',
folder: 'premium-videos'
})
```
### Video with Reference Images
Use reference images to guide the video generation with visual context (image-to-video mode).
```typescript
const productVideo = await cosmic.ai.generateVideo({
prompt: 'Product rotates smoothly revealing all angles with soft studio lighting',
duration: 8,
resolution: '720p',
reference_images: [
'https://cdn.cosmicjs.com/product-hero.jpg'
],
metadata: {
product_id: 'prod_123',
campaign: 'product-launch-2024'
},
folder: 'ai-videos'
})
console.log(`Generated video: ${productVideo.media.url}`)
```
### Multiple Reference Images
Provide up to 3 reference images for style, content, or character consistency.
```typescript
const styledVideo = await cosmic.ai.generateVideo({
prompt: 'Character walks through a vibrant marketplace with people and colors matching the reference style',
duration: 8,
reference_images: [
'https://cdn.cosmicjs.com/character-ref-1.jpg',
'https://cdn.cosmicjs.com/style-ref.jpg',
'https://cdn.cosmicjs.com/color-palette.jpg'
]
})
```
### With Custom Metadata
```typescript
const video = await cosmic.ai.generateVideo({
prompt: 'Time-lapse of a flower blooming with butterflies around',
duration: 8,
metadata: {
project: 'nature-series',
episode: 3,
scene: 'flower-bloom',
tags: ['nature', 'time-lapse', 'flowers']
}
})
```
### Video Extension
Extend a previously generated Veo video to create longer content:
```typescript
// First, generate an initial video
const initialVideo = await cosmic.ai.generateVideo({
prompt: 'A calico kitten sitting peacefully in golden sunlight',
duration: 8,
resolution: '720p'
})
// Then extend it with a continuation
const extendedVideo = await cosmic.ai.extendVideo({
media_id: initialVideo.media.id,
prompt: 'The kitten stands up and walks away into the garden'
})
console.log('Extended video:', extendedVideo.media.url)
console.log('Source video ID:', extendedVideo.source_media_id)
```
### Chain Multiple Extensions
Create longer narratives by chaining multiple 8-second extensions:
```typescript
// Build a 32-second video (4 segments)
let currentVideo = await cosmic.ai.generateVideo({
prompt: 'Opening scene: sunrise over mountains',
duration: 8
})
const segments = [currentVideo]
for (const continuation of [
'Birds take flight from the trees below',
'A hiker appears on the trail in the distance',
'Close-up of the hiker reaching the summit'
]) {
currentVideo = await cosmic.ai.extendVideo({
media_id: currentVideo.media.id,
prompt: continuation
})
segments.push(currentVideo)
}
console.log(`Created ${segments.length} connected segments (${segments.length * 8}s total)`)
```
### Error Handling
```typescript
try {
const video = await cosmic.ai.generateVideo({
prompt: 'A beautiful sunset over the ocean',
duration: 8
})
console.log('Video generated successfully:', video.media.url)
} catch (error) {
if (error.message.includes('token')) {
console.error('Insufficient tokens:', error.message)
} else if (error.message.includes('prompt')) {
console.error('Invalid prompt:', error.message)
} else {
console.error('Generation failed:', error.message)
}
}
```
## Model Options
### Veo 3.1 Fast (Recommended)
```typescript
model: 'veo-3.1-fast-generate-preview' // Default
```
- **Generation Time**: 30-90 seconds
- **Token Cost**: 144,000-288,000 output tokens
- **Best For**: Most use cases, quick turnaround
### Veo 3.1 Standard (Premium Quality)
```typescript
model: 'veo-3.1-generate-preview'
```
- **Generation Time**: 60-180 seconds
- **Token Cost**: 384,000-768,000 output tokens
- **Best For**: Premium cinematic quality, hero content
## Token Costs
Video generation and extension costs are billed as **output tokens**:
### Veo 3.1 Fast
| Feature | Output Tokens | Approx. Cost |
|---------|---------------|--------------|
| 4 second video | 144,000 | $0.60 |
| 6 second video | 216,000 | $0.90 |
| 8 second video | 288,000 | $1.20 |
| Video extension | 288,000 | $1.20 |
### Veo 3.1 Standard
| Feature | Output Tokens | Approx. Cost |
|---------|---------------|--------------|
| 4 second video | 384,000 | $1.60 |
| 6 second video | 576,000 | $2.40 |
| 8 second video | 768,000 | $3.20 |
| Video extension | 768,000 | $3.20 |
**Note**: Video generation is significantly more expensive than image generation. A single 8-second video costs the same as approximately 60 DALL-E 3 images. Video extensions always produce 8-second clips.
## Technical Specifications
- **Format**: MP4 with H.264 encoding
- **Durations**: 4, 6, or 8 seconds
- **Resolutions**: 720p (1280×720) or 1080p (1920×1080)
- **Audio**: Native stereo audio generation included
- **File Size**: Typically 5-15MB depending on duration and resolution
- **Generation Time**: 30-90s (Fast), 60-180s (Standard)
- **Reference Images**: Up to 3 images (image-to-video mode)
## Tips for Best Results
### Writing Effective Prompts
1. **Be specific about motion**: "Camera slowly zooms in" vs "camera moves"
2. **Describe lighting**: "soft studio lighting", "golden hour sunlight"
3. **Include atmosphere**: "vibrant colors", "dramatic depth of field"
4. **Specify camera angles**: "close-up", "wide shot", "aerial view"
### Using Reference Images
1. **Image-to-Video Mode**: The first reference image becomes the starting frame
2. **Style Consistency**: Provide 2-3 images showing the desired visual style
3. **Character Consistency**: Multiple angles help maintain character appearance
4. **Product Videos**: Show your product from key angles for accurate representation
### Optimization
1. **Use Fast model for iteration**: Quickly test prompts with the fast model
2. **Switch to Standard for finals**: Use premium quality for final deliverables
3. **Start with 4s duration**: Shorter videos generate faster and cost less
4. **Batch similar videos**: Generate multiple variations in one session
## TypeScript Support
The SDK is written in TypeScript and provides full type definitions:
```typescript
import {
createBucketClient,
GenerateVideoOptions,
VideoGenerationResponse,
ExtendVideoOptions,
VideoExtensionResponse
} from '@cosmicjs/sdk'
// Type-safe video generation
const generateOptions: GenerateVideoOptions = {
prompt: 'A peaceful zen garden with raking sand patterns',
model: 'veo-3.1-fast-generate-preview',
duration: 8,
resolution: '720p'
}
const video: VideoGenerationResponse = await cosmic.ai.generateVideo(generateOptions)
// Type-safe video extension
const extendOptions: ExtendVideoOptions = {
media_id: video.media.id,
prompt: 'Camera slowly pans to reveal the sunset'
}
const extended: VideoExtensionResponse = await cosmic.ai.extendVideo(extendOptions)
```
## Related Documentation
- [AI Image Generation](https://www.cosmicjs.com/docs/api/ai#generate-image)
- [AI Text Generation](https://www.cosmicjs.com/docs/api/ai#generate-text)
- [Token Usage & Pricing](https://www.cosmicjs.com/pricing)
- [Media Management](https://www.cosmicjs.com/docs/api/media)
## Support
For questions or issues:
- [Documentation](https://www.cosmicjs.com/docs)
- [GitHub Issues](https://github.com/cosmicjs/cosmic-sdk-js/issues)
- [Community Slack](https://cosmicjs.com/community)