# Seedance 2.5 API 文档

> 通过 AI Studio API 使用 Seedance 2.5 模型生成视频。

## 概览

使用 AI Studio API 创建 Seedance 2.5 生成任务并查询任务状态。接口采用异步流程：先创建任务拿到 `taskId`，再通过任务查询接口轮询结果。

## 认证方式

所有请求都需要在 `Authorization` 请求头中携带 API Key。

```http
Authorization: Bearer YOUR_API_KEY
```

## 可用模型

| modelId | 版本 | 服务商 | 运行模型 |
| --- | --- | --- | --- |
| `video:fal-bytedance-seedance-2-5-text-to-video` | Text to Video | ByteDance | bytedance/seedance-2.5/text-to-video |
| `video:fal-bytedance-seedance-2-5-image-to-video` | Image to Video | ByteDance | bytedance/seedance-2.5/image-to-video |
| `video:fal-bytedance-seedance-2-5-reference-to-video` | Reference to Video | ByteDance | bytedance/seedance-2.5/reference-to-video |
| `video:bytedance-seedance-2-5` | Seedance 2.5 | Bytedance Seedance 2.5 | bytedance/seedance-2-5 |

## 1. 创建生成任务

### 接口地址

```http
POST https://localhost:3000/api/ai-studio/execute
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

### 请求示例

```json
{
  "modelId": "video:fal-bytedance-seedance-2-5-text-to-video",
  "isPublic": true,
  "payload": {
    "generate_audio": true,
    "resolution": "720p",
    "duration": "auto",
    "prompt": "An octopus finds a football in the ocean and excitedly calls its octopus friends to come and play. Cut scene to an octopus football game under the sea.",
    "end_user_id": "",
    "bitrate_mode": "standard",
    "aspect_ratio": "auto"
  }
}
```

### 成功响应

```json
{
  "success": true,
  "data": {
    "modelId": "video:fal-bytedance-seedance-2-5-text-to-video",
    "generationId": "generation-id",
    "reservedCredits": 20,
    "taskId": "provider-task-id",
    "state": "queued"
  }
}
```

## 2. 查询任务状态

### 接口

```http
GET https://localhost:3000/api/ai-studio/tasks/{taskId}
Authorization: Bearer YOUR_API_KEY
```

### 成功响应

```json
{
  "success": true,
  "data": {
    "generationId": "generation-id",
    "taskId": "provider-task-id",
    "modelId": "video:fal-bytedance-seedance-2-5-text-to-video",
    "state": "succeeded",
    "mediaUrls": [
      "https://example.com/result.mp4"
    ],
    "reservedCredits": 20,
    "refundedCredits": 0
  }
}
```

## 请求字段

### Text to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `generate_audio` | boolean | 否 | `true` | - | Whether to generate synchronized audio for the video, including sound effects, ambient sounds, and lip-synced speech. The cost of video generation is the same regardless of whether audio is generated or not. |
| `resolution` | enum | 否 | `"720p"` | 480p, 720p, 1080p | Video resolution - 480p for faster generation, 720p for balance, 1080p for high quality. |
| `duration` | enum | 否 | `"auto"` | auto, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 | Duration of the video in seconds. Supports 4 to 30 seconds, or auto to let the model decide based on the prompt. |
| `prompt` | string | 是 | `"An octopus finds a football in the ocean and excitedly calls its octopus friends to come and play. Cut scene to an octopus football game under the sea."` | - | The text prompt used to generate the video |
| `end_user_id` | object | 否 | `-` | - | The unique user ID of the end user. |
| `bitrate_mode` | enum | 否 | `"standard"` | standard, high | Output bitrate mode. 'high' requests a higher-quality, larger-file encode from the model; 'standard' uses the default bitrate. |
| `aspect_ratio` | enum | 否 | `"auto"` | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | The aspect ratio of the generated video. Use 16:9 for landscape, 9:16 for portrait/vertical, 1:1 for square, 21:9 for ultrawide cinematic, or auto to let the model decide. |

#### input 字段

_该模型暂无字段配置。_

### Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `duration` | enum | 否 | `"auto"` | auto, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 | Duration of the video in seconds. Supports 4 to 30 seconds, or auto to let the model decide based on the prompt. |
| `prompt` | string | 是 | `"An octopus finds a football in the ocean and excitedly calls its octopus friends to come and play. Cut scene to an octopus football game under the sea."` | - | The text prompt describing the desired motion and action for the video. |
| `generate_audio` | boolean | 否 | `true` | - | Whether to generate synchronized audio for the video, including sound effects, ambient sounds, and lip-synced speech. The cost of video generation is the same regardless of whether audio is generated or not. |
| `image_url` | string | 是 | `"https://v3b.fal.media/files/b/0a8eba37/Cqg-4Uwzyz4DELfceT1CF_a17e588773ec45b1a9e6f100a787b80b.jpg"` | - | The URL of the starting frame image to animate. Supported formats: JPEG, PNG, WebP. Max 30 MB. |
| `resolution` | enum | 否 | `"720p"` | 480p, 720p, 1080p | Video resolution - 480p for faster generation, 720p for balance, 1080p for high quality. |
| `end_image_url` | object | 否 | `-` | - | The URL of the image to use as the last frame of the video. When provided, the generated video will transition from the starting image to this ending image. Supported formats: JPEG, PNG, WebP. Max 30 MB. |
| `end_user_id` | object | 否 | `-` | - | The unique user ID of the end user. |
| `bitrate_mode` | enum | 否 | `"standard"` | standard, high | Output bitrate mode. 'high' requests a higher-quality, larger-file encode from the model; 'standard' uses the default bitrate. |
| `aspect_ratio` | string | 否 | `"auto"` | - | The aspect ratio of the generated video. Always "auto" for image-to-video |

#### input 字段

_该模型暂无字段配置。_

### Reference to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `task` | enum | 否 | `"reference"` | reference, editing, extension | The type of video generation task. Reference uses the supplied media as guidance. Editing modifies a reference video and automatically coerces aspect_ratio and duration to auto. Extension continues a reference video and automatically coerces aspect_ratio to auto. |
| `bitrate_mode` | enum | 否 | `"standard"` | standard, high | Output bitrate mode. 'high' requests a higher-quality, larger-file encode from the model; 'standard' uses the default bitrate. |
| `duration` | enum | 否 | `"auto"` | auto, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 | Duration of the video in seconds. Supports 4 to 30 seconds, or auto to let the model decide based on the prompt. |
| `prompt` | string | 是 | `"An octopus finds a football in the ocean and excitedly calls its octopus friends to come and play. Cut scene to an octopus football game under the sea."` | - | The text prompt used to generate the video. |
| `video_urls` | string[] | 否 | `-` | - | Reference videos to guide video generation. Refer to them in the prompt as @Video1, @Video2, etc. Supported formats: MP4, MOV. Up to 10 videos. Each video must be 1.8 to 30.2 seconds and no larger than 200 MB; combined duration must not exceed 30.2 seconds. Dimensions must be 300 to 6,000 pixels per side, aspect ratio 0.4 to 2.5, and frame rate 24 to 60 FPS. |
| `generate_audio` | boolean | 否 | `true` | - | Whether to generate synchronized audio for the video, including sound effects, ambient sounds, and lip-synced speech. The cost of video generation is the same regardless of whether audio is generated or not. |
| `audio_urls` | string[] | 否 | `-` | - | Reference audio to guide video generation. Refer to them in the prompt as @Audio1, @Audio2, etc. Supported formats: MP3, WAV. Up to 10 files. Each file must be 1.8 to 30.2 seconds and no larger than 15 MB; combined duration must not exceed 30.2 seconds. At least one reference image or video is required. |
| `resolution` | enum | 否 | `"720p"` | 480p, 720p, 1080p | Video resolution - 480p for faster generation, 720p for balance, 1080p for high quality. |
| `seed` | object | 否 | `-` | - | Random seed for reproducibility. Note that results may still vary slightly even with the same seed. |
| `end_user_id` | object | 否 | `-` | - | The unique user ID of the end user. |
| `image_urls` | string[] | 否 | `["https://v3b.fal.media/files/b/0a8eba37/Cqg-4Uwzyz4DELfceT1CF_a17e588773ec45b1a9e6f100a787b80b.jpg"]` | - | Reference images to guide video generation. Refer to them in the prompt as @Image1, @Image2, etc. Supported formats: JPG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF. Max 30 MB per image. Up to 30 images. Total files across all modalities must not exceed 50. |
| `aspect_ratio` | enum | 否 | `"auto"` | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | The aspect ratio of the generated video. Use 16:9 for landscape, 9:16 for portrait/vertical, 1:1 for square, 21:9 for ultrawide cinematic, or auto to let the model decide. |

#### input 字段

_该模型暂无字段配置。_

### Seedance 2.5

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"bytedance/seedance-2-5"` | bytedance/seedance-2-5 | The model name to use for generation. Required field. - Must be `bytedance/seedance-2-5` for this endpoint |
| `input` | object | 是 | `-` | - | Input parameters for the generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 否 | `"A serene beach at sunset with waves gently crashing on the shore, palm trees swaying in the breeze, and seagulls flying across the orange sky"` | - | The text prompt used to generate the video.. ( Max length: 30000 characters) |
| `first_frame_url` | string | 否 | `-` | - | First frame image url or asset://{assetId} (for example: asset://asset-20260404242101-76djj)<br>Cannot be used simultaneously with reference_image_urls, reference_video_urls, or reference_audio_urls. |
| `last_frame_url` | string | 否 | `-` | - | End frame image url or asset://{assetId} (for example: asset://asset-20260404242101-76djj)<br>last_frame_url cannot be passed alone; first_frame_url must be provided together with it. |
| `reference_image_urls` | string[] | 否 | `["https://file.aiquickdraw.com/custom-page/akr/section-images/example1.png"]` | - | Enter a list of image URLs or asset://{assetId} (for example: asset://asset-20260404242101-76djj).<br>Single image requirements:<br>Format: jpeg, png, webp, bmp, tiff, gif.<br>Aspect ratio (width/height): (0.4, 2.5)<br>Width and height (px): (300, 6000)<br>Size: Single image less than 30 MB.<br>Maximum number of files: The sum of the number of frames at the beginning and end must not exceed 30.<br>Mutually exclusive with the first/last-frame scenario; |
| `reference_video_urls` | string[] | 否 | `-` | - | Enter a list of video URLs or asset://{assetId} (for example: asset://asset-20260404242101-76djj) .<br>Single video requirements:<br>Video format: mp4, mov.<br>Resolution: 480p, 720p<br>Dimensions:<br>Aspect ratio (width/height): [0.4, 2.5]<br>Width/height (px): [300, 6000]<br>Total pixels: [640×640=409600, 834×1112=927408], i.e., the product of width and height must meet the range requirement of [409600, 927408].<br>Size: Single video not exceeding 200 MB.<br>Frame rate (FPS): [24, 60]<br>Single video duration: [2, 30] seconds; Mutually exclusive with the first/last-frame scenario; Total duration of reference videos must not exceed 30 seconds. |
| `reference_audio_urls` | string[] | 否 | `-` | - | Enter a list of audio URLs or asset://{assetId} (for example: asset://asset-20260404242101-76djj) .<br>Single audio requirements:<br>Format: wav, mp3<br>Size: Single audio file size not exceeding 15 MB.<br>Single audio duration: [2, 30] seconds; Mutually exclusive with the first/last-frame scenario; Total duration of reference videos must not exceed 30 seconds. |
| `return_last_frame` | boolean | 否 | `false` | - | Whether to return the last frame of the video. When draft=true, this parameter cannot be set to true. |
| `generate_audio` | boolean | 否 | `true` | - | Whether to generate audio for the video. - **true**: Generate with audio (higher cost)<br>- **false**: Generate without audio Note: Enabling audio will increase the generation cost |
| `resolution` | enum | 否 | `"720p"` | 480p, 720p, 1080p | Video resolution - 480p for faster generation, 720p for balance. |
| `aspect_ratio` | enum | 否 | `"adaptive"` | 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive | Video aspect ratio configuration. |
| `duration` | number | 否 | `5` | - | Video duration in seconds, from 4 to 30. |
| `output_format` | enum | 否 | `"mp4"` | mp4, mov | Video output format. |
| `web_search` | boolean | 否 | `-` | - | Enable online search. |
| `nsfw_checker` | boolean | 否 | `-` | - | Defaults to false. You can set it to false based on your needs. If set to false, our content filtering will be disabled, and all results will be returned directly by the model itself.<br>Note: There is no guarantee that everything can be filtered out; if you are not satisfied with the results, you will need to make your own arrangements. |

## 价格

创建生成任务时会预扣积分。创建任务响应中的 `reservedCredits` 是本次请求最终预留的积分数量。

| 模型 | 类型 | 规格 | 价格 | 计费方式 |
| --- | --- | --- | --- | --- |
| Text to Video | 文生视频 | 480p | 44.1 积分/秒 | 输出秒数 × 44.1 |
| Text to Video | 文生视频 | 720p | 94.6 积分/秒 | 输出秒数 × 94.6 |
| Text to Video | 文生视频 | 1080p | 232.8 积分/秒 | 输出秒数 × 232.8 |
| Image to Video | 图生视频 | 480p | 44.1 积分/秒 | 输出秒数 × 44.1 |
| Image to Video | 图生视频 | 720p | 94.6 积分/秒 | 输出秒数 × 94.6 |
| Image to Video | 图生视频 | 1080p | 232.8 积分/秒 | 输出秒数 × 232.8 |
| Reference to Video | 文/图生视频 | 480p | 44.1 积分/秒 | 输出秒数 × 44.1 |
| Reference to Video | 视频转视频 | 480p | 26.5 积分/秒 | （输入秒数 + 输出秒数）× 26.5 |
| Reference to Video | 文/图生视频 | 720p | 94.6 积分/秒 | 输出秒数 × 94.6 |
| Reference to Video | 视频转视频 | 720p | 56.8 积分/秒 | （输入秒数 + 输出秒数）× 56.8 |
| Reference to Video | 文/图生视频 | 1080p | 232.8 积分/秒 | 输出秒数 × 232.8 |
| Reference to Video | 视频转视频 | 1080p | 139.7 积分/秒 | （输入秒数 + 输出秒数）× 139.7 |
| Seedance 2.5 | 视频转视频 | 480p | 17 积分/秒 | （输入秒数 + 输出秒数）× 17 |
| Seedance 2.5 | 文/图生视频 | 480p | 28 积分/秒 | 输出秒数 × 28 |
| Seedance 2.5 | 视频转视频 | 720p | 38 积分/秒 | （输入秒数 + 输出秒数）× 38 |
| Seedance 2.5 | 文/图生视频 | 720p | 63 积分/秒 | 输出秒数 × 63 |
| Seedance 2.5 | 视频转视频 | 1080p | 68.5 积分/秒 | （输入秒数 + 输出秒数）× 68.5 |
| Seedance 2.5 | 文/图生视频 | 1080p | 114 积分/秒 | 输出秒数 × 114 |

## 常见错误

| 状态 | 含义 |
| --- | --- |
| `400` | Invalid request payload |
| `401` | Missing or invalid API key |
| `402` | Insufficient credits or plan limit |
| `404` | Model or task not found |
| `429` | Rate limit exceeded |
| `500` | Server error |