> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Video

> Generate videos from text prompts and images

The `video()` method generates videos from text descriptions using AI models like Runway, Kling, and Luma.

## Basic Video Generation

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A serene ocean sunset with gentle waves rolling onto a sandy beach'
  }
});

console.log(response.videos[0].url);
console.log('Duration:', response.videos[0].duration, 'seconds');
console.log('Cost:', response.cost);
```

## Video Sizes

Control video dimensions and aspect ratio:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A bustling city street at night',
    size: '1280x720'  // Landscape HD
  }
});
```

### Supported Sizes

| Size        | Aspect Ratio | Use Case                  |
| ----------- | ------------ | ------------------------- |
| `1280x720`  | 16:9         | Landscape/YouTube         |
| `720x1280`  | 9:16         | Portrait/TikTok/Instagram |
| `1024x1792` | 9:16         | Portrait/high-res         |
| `1792x1024` | 16:9         | Landscape/high-res        |

<Tip>
  Use `720x1280` for social media vertical videos (TikTok, Instagram Reels, YouTube Shorts).
</Tip>

## Video Duration

Set how long the video should be:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Time-lapse of clouds moving across a blue sky',
    duration: 10  // 10 seconds
  }
});
```

<Note>
  Supported durations vary by model. Most support 5-10 seconds. Check your gate's model capabilities.
</Note>

## Image-to-Video

Generate video from a starting image:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Camera slowly zooms into the building',
    image: {
      url: 'https://example.com/building.jpg'
    }
  }
});
```

### Base64 Images

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'The flower blooms and petals unfold',
    image: {
      base64: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...'
    }
  }
});
```

## Reference Images

Guide video generation with reference images:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A person walking through a forest',
    referenceImages: [
      {
        url: 'https://example.com/person.jpg',
        referenceType: 'subject'  // Keep this person's appearance
      },
      {
        url: 'https://example.com/forest-style.jpg',
        referenceType: 'style'  // Match this artistic style
      }
    ]
  }
});
```

### Reference Types

| Type      | Purpose                     |
| --------- | --------------------------- |
| `subject` | Maintain subject appearance |
| `style`   | Match artistic style        |
| `asset`   | Include specific objects    |

## Advanced Parameters

### FPS (Frames Per Second)

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Smooth camera pan across a mountain range',
    fps: 30  // Smoother motion
  }
});
```

### Negative Prompts

Specify what to avoid:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A peaceful garden scene',
    negativePrompt: 'people, cars, buildings, modern objects'
  }
});
```

### Multiple Videos

Generate variations:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Aurora borealis dancing in the night sky',
    numberOfVideos: 3  // Generate 3 variations
  }
});

response.videos.forEach((video, i) => {
  console.log(`Video ${i + 1}:`, video.url);
});
```

### Deterministic Generation

Use seeds for reproducible results:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Abstract colorful patterns morphing',
    seed: 42  // Same seed + prompt = same video
  }
});
```

## Parameters

### Request Parameters

| Parameter          | Type               | Default       | Description                  |
| ------------------ | ------------------ | ------------- | ---------------------------- |
| `prompt`           | `string`           | Required      | Video description            |
| `duration`         | `number \| string` | Model default | Video length in seconds      |
| `size`             | `string`           | Model default | Video dimensions             |
| `fps`              | `number`           | Model default | Frames per second            |
| `seed`             | `number`           | Random        | Seed for reproducibility     |
| `negativePrompt`   | `string`           | None          | What to avoid                |
| `numberOfVideos`   | `number`           | 1             | Number of videos to generate |
| `image`            | `object`           | None          | Starting image               |
| `lastFrame`        | `object`           | None          | Ending image                 |
| `referenceImages`  | `array`            | None          | Style/subject references     |
| `personGeneration` | `string`           | None          | Person generation mode       |

## Response

```typescript theme={null}
interface VideoResponse {
  id: string;                    // Request ID
  model: string;                 // Model used
  videos: VideoOutput[];         // Generated videos
  cost: number;                  // Request cost in USD
  latency: number;               // Response time in ms
}

interface VideoOutput {
  url?: string;                  // Hosted video URL
  base64?: string;               // Base64-encoded video data
  duration?: number;             // Video length in seconds
  revisedPrompt?: string;        // AI-revised prompt
}
```

## Best Practices

### 1. Write Motion-Focused Prompts

```typescript theme={null}
// Good ✅ - Describes movement
{
  prompt: 'Camera slowly pans right across a mountain landscape, revealing a lake in the distance'
}

// Less effective - Static description
{
  prompt: 'A mountain landscape with a lake'
}
```

### 2. Be Specific About Camera Movement

```typescript theme={null}
// Good ✅ - Clear camera direction
{
  prompt: 'Drone shot rising up from ground level, revealing a coastal town at sunset'
}

// Good ✅ - Detailed motion
{
  prompt: 'Close-up of raindrops hitting a window, camera slowly pulling back to reveal a city view'
}
```

### 3. Use Appropriate Dimensions

```typescript theme={null}
// Good ✅ - Vertical for social media
{
  prompt: 'Fashion model walking down a runway',
  size: '720x1280'  // TikTok/Instagram format
}

// Good ✅ - Landscape for YouTube
{
  prompt: 'Product demonstration video',
  size: '1280x720'  // YouTube format
}
```

### 4. Always Handle Errors

```typescript theme={null}
try {
  const response = await verlon.video({
    gateId: 'your-gate-id',
    data: {
      prompt: 'A sunset over the mountains'
    }
  });

  return response.videos[0].url;
} catch (error) {
  console.error('Video generation failed:', error);
  return null;
}
```

### 5. Monitor Costs

Video generation is more expensive than images:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Ocean waves',
    duration: 10
  }
});

console.log(`Duration: ${response.videos[0].duration}s`);
console.log(`Cost: $${response.cost.toFixed(4)}`);
console.log(`Cost per second: $${(response.cost / response.videos[0].duration).toFixed(4)}`);
```

## Examples

### Social Media Content

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  metadata: { platform: 'instagram' },
  data: {
    prompt: 'Product reveal: sleek smartphone rotating on a pedestal with studio lighting',
    size: '720x1280',  // Vertical
    duration: 5
  }
});
```

### Marketing Video

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Aerial drone shot flying over a modern office building, smooth descent revealing the entrance',
    size: '1280x720',  // Landscape
    duration: 10,
    fps: 30
  }
});
```

### Animation from Image

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'The character turns their head and smiles at the camera',
    image: {
      url: 'https://example.com/character.jpg'
    },
    duration: 5
  }
});
```

### Nature Scene

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Time-lapse of sunrise over a misty forest, camera slowly panning left',
    size: '1792x1024',
    duration: 8,
    negativePrompt: 'people, buildings, cars'
  }
});
```

### Style-Consistent Video

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A cat playing with a ball of yarn',
    referenceImages: [
      {
        url: 'https://example.com/art-style.jpg',
        referenceType: 'style'
      }
    ],
    duration: 6
  }
});
```

## Advanced Usage

### Batch Generation

Generate multiple videos:

```typescript theme={null}
const prompts = [
  'Waves crashing on a beach',
  'City traffic at night',
  'Leaves falling in autumn'
];

const videos = await Promise.all(
  prompts.map(prompt =>
    verlon.video({
      gateId: 'your-gate-id',
      data: { prompt, size: '1280x720' }
    })
  )
);

videos.forEach((response, i) => {
  console.log(prompts[i], '->', response.videos[0].url);
});
```

### Override Model

Use a specific video model:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  model: 'runway-gen3',  // Force specific model
  data: {
    prompt: 'A futuristic city scene'
  }
});
```

### Custom Metadata

Track video generation:

```typescript theme={null}
const response = await verlon.video({
  gateId: 'your-gate-id',
  metadata: {
    userId: 'user-123',
    campaign: 'summer-launch',
    platform: 'youtube-shorts'
  },
  data: {
    prompt: 'Product demonstration with dynamic camera movement',
    size: '720x1280',
    duration: 15
  }
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Images" icon="image" href="/sdk-reference/images">
    Generate static images
  </Card>

  <Card title="Audio" icon="microphone" href="/sdk-reference/audio">
    Add voiceover with text-to-speech
  </Card>

  <Card title="Gates & Routing" icon="route" href="/concepts/gates-and-routing">
    How Verlon routes video requests
  </Card>

  <Card title="Cost Tracking" icon="chart-line" href="/concepts/cost-tracking">
    Monitor video generation costs
  </Card>
</CardGroup>