# Seedance 2.5 API

Complete API reference for Seedance 2.5 video generation models by ByteDance.

## Model Variants

This API supports three model variants:

| Model | ID | Description |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | High-quality text-to-video generation |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | First-frame or first-and-last-frame video generation |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | Video generation guided by reference images, videos, and audio |

## Quick Comparison

| Feature | Text to Video | Image to Video | Reference to Video |
|---------|---------------|----------------|--------------------|
| Duration Range | 4-30 seconds | 4-30 seconds | 4-30 seconds |
| Resolution Options | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Aspect Ratio | Required | Not supported | Required |
| Required Media | None | First-frame image | None |
| Optional Media | None | Last-frame image | Images, videos, and audio |

### Supported Aspect Ratios

Text-to-Video and Reference-to-Video support:

`21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`

Image-to-Video does not support the `aspect_ratio` parameter.

### Resolution Options

| Resolution | Description |
|------------|-------------|
| `480p` | Standard definition |
| `720p` | High definition |
| `1080p` | Full HD |

## Seedance 2.5 Text to Video

### Endpoint

```
POST /api/v1/video/task
```

### Request Parameters

#### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_name` | string | Must be `"seedance-v2.5-text-to-video"` |
| `prompt` | string | Video generation prompt |
| `resolution` | string | Output resolution: `"480p"`, `"720p"`, or `"1080p"` |
| `duration` | integer | Video duration in whole seconds (4-30), in steps of 1 |
| `aspect_ratio` | string | Video aspect ratio: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, or `"3:4"` |

#### Optional

| Parameter | Type | Description |
|-----------|------|-------------|
| `sound` | boolean | Whether to generate sound. Defaults to `true` |

### Example Request

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/video/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'seedance-v2.5-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    resolution: '720p',
    duration: 8,
    aspect_ratio: '16:9',
    sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## Seedance 2.5 Image to Video

### Request Parameters

#### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_name` | string | Must be `"seedance-v2.5-image-to-video"` |
| `prompt` | string | Video generation prompt |
| `resolution` | string | Output resolution: `"480p"`, `"720p"`, or `"1080p"` |
| `duration` | integer | Video duration in whole seconds (4-30), in steps of 1 |
| `image_url` | string | First-frame image URL |

#### Optional

| Parameter | Type | Description |
|-----------|------|-------------|
| `image_end_url` | string | Optional last-frame image URL |
| `sound` | boolean | Whether to generate sound. Defaults to `true` |

> Do not include `aspect_ratio` in Image-to-Video requests. This model does not support that parameter.

### Example Request

```javascript
{
  model_name: 'seedance-v2.5-image-to-video',
  image_url: 'https://example.com/first-frame.jpg',
  image_end_url: 'https://example.com/last-frame.jpg',
  prompt: 'Camera slowly pulls back to reveal the full landscape',
  resolution: '720p',
  duration: 8,
  sound: true
}
```

## Seedance 2.5 Reference to Video

### Request Parameters

#### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_name` | string | Must be `"seedance-v2.5-reference-to-video"` |
| `prompt` | string | Video generation prompt. Write a standard prompt without placeholders, or optionally use the @ (AT) reference feature with `<<<image_N>>>`, `<<<video_N>>>`, and `<<<audio_N>>>` to explicitly reference items from the corresponding media arrays |
| `resolution` | string | Output resolution: `"480p"`, `"720p"`, or `"1080p"` |
| `duration` | integer | Video duration in whole seconds (4-30), in steps of 1 |
| `aspect_ratio` | string | Video aspect ratio: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, or `"3:4"` |

#### Reference Media

All reference media are optional. Image-only, video-only, audio-only, and requests without reference media are supported. For generation without references, Text-to-Video is recommended.

| Parameter | Type | Description |
|-----------|------|-------------|
| `images` | string[] | 0-30 reference image URLs; see Media Limits below |
| `videos` | string[] | 0-10 reference video URLs in MP4 or MOV format; each video must be 2-30 seconds, with a combined duration of at most 30 seconds |
| `audios` | string[] | 0-10 reference audio URLs in WAV or MP3 format; each audio must be 2-30 seconds and no larger than 15 MB, and their total duration must not exceed 30 seconds |

#### @ (AT) Reference Placeholders

The @ (AT) reference feature links reference media to the prompt through numbered `<<<...>>>` placeholders. Numbering starts at `1` independently for each media type and follows the order of the corresponding array:

| Placeholder | Referenced value |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

For example, if the first image is a character reference and the second image is a scene reference, use `<<<image_1>>>` for the character and `<<<image_2>>>` for the scene in `prompt`. Each placeholder must point to an item that exists in its corresponding array.

#### Optional

| Parameter | Type | Description |
|-----------|------|-------------|
| `sound` | boolean | Whether to generate sound. Defaults to `true` |

### Example Request

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere',
  resolution: '720p',
  duration: 8,
  aspect_ratio: '16:9',
  sound: true,
  images: ['https://example.com/subject-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4'],
  audios: ['https://example.com/atmosphere-reference.mp3']
}
```

### @ (AT) Reference-to-Video Request Example

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Place the explorer from <<<image_1>>> in the environment from <<<image_2>>>, following the camera movement in <<<video_1>>> and speaking with the reference voice from <<<audio_1>>>',
  resolution: '720p',
  duration: 10,
  aspect_ratio: '16:9',
  sound: true,
  images: [
    'https://example.com/explorer-reference.jpg',
    'https://example.com/environment-reference.png'
  ],
  videos: ['https://example.com/camera-movement-reference.mp4'],
  audios: ['https://example.com/voice-reference.mp3']
}
```

## Media Limits

These limits apply to first-frame images, last-frame images, and reference media for the models on this page.

| Media | Formats | Limits |
|-------|---------|--------|
| Images | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Each image must be smaller than 30 MB; width and height must each be 300-6000 px; width-to-height ratio must be 0.4-2.5 |
| Videos | MP4, MOV | At most 200 MB each; width and height must each be 300-6000 px; width-to-height ratio must be 0.4-2.5; frame rate must be 24-60 FPS |
| Audio | WAV, MP3 | At most 15 MB each |
| Request body | — | At most 64 MB |

Reference audio and reference video each have a separate combined duration limit of 30 seconds. Their counts are independent: up to 30 images, 10 videos, and 10 audio clips. Adding videos does not reduce the image allowance.

All models default to `720p`, but `resolution` must still be supplied. The sound switch defaults to `true`; neither this switch nor reference audio changes the price.

## Response Format

### Initial Response

All models return a `task_id` for polling:

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "submitted"
  }
}
```

### Polling Response

Poll `GET /api/v1/video/{taskId}` to check status:

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "succeed",
    "task_status_msg": null,
    "task_result": {
      "credit": 0.2,
      "videos": [
        {
          "url": "https://example.com/generated-video.mp4"
        }
      ]
    }
  }
}
```

### Status Values

- `submitted`: Task accepted and waiting to be processed
- `processing`: Video generation in progress
- `succeed`: Video generation completed
- `failed`: Video generation failed

## Processing Time

Processing time varies by duration, resolution, and current queue conditions.

Poll every 5-10 seconds to check status.

## Best Practices

1. **Required Parameters**: Always provide `resolution` and `duration`, and provide `aspect_ratio` for Text-to-Video and Reference-to-Video
2. **Image-to-Video Ratio**: Do not send `aspect_ratio` for Image-to-Video requests
3. **Reference Videos**: Videos are optional; each video and the combined video duration must stay within the documented limits
4. **Reference Images**: Images are optional independently of videos and audio; submit up to 30 supported image URLs
5. **Reference Audio**: Keep every audio clip within 2-30 seconds and 15 MB, with a combined duration of no more than 30 seconds
6. **Reference Ordering**: Keep `images`, `videos`, and `audios` in intentional order and refer to them consistently in the prompt
7. **Sound**: Omit `sound` to use its default value of `true`, or set it to `false` to disable generated sound