# Seedance 2.5 全能参考 API Documentation

> Seedance 2.5 是 ByteDance 推出的一款多模态 AI 视频模型，支持逼真人像视频生成。它能够通过文本、图像、视频和音频等多模态参考素材，生成具备极强多镜头一致性和原生音频的电影级连贯视频。

## Overview

This document describes how to call the **Seedance 2.5 全能参考** API.

- **Model / path slug**: `video/seedancevtpf`
- **Task type**: `async` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/39`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `POST https://apis.xiaobao.ink/api/video/seedancevtpf`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `POST`

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | 用于视频生成的文本提示词。必填字段。（最小长度：3，最大长度：20000 字符） |
| `first_frame_url` | Yes | 首帧图片 |
| `last_frame_url` | Yes | 尾帧图片 |
| `reference_image_urls` | Yes | 传入单张图片要求: 格式：jpeg、png、webp、bmp、tiff、gif。 宽高比（宽/高）： (0.4, 2.5) 宽高长度（px）：(300, 6000) 大小：单张图片小于 30 MB。 最大文件数：和首尾帧张数之和不得超过9张。 |
| `reference_video_urls` | Yes | 单个视频要求: 视频格式：mp4、mov。 分辨率：480p、720p 时长：单个视频时长 [2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。 尺寸： 宽高比（宽/高）：[0.4, 2.5] 宽高长度（px）：[300, 6000] 总像素数：[640×640=409600, 834×1112=927408]，即宽和高的乘积符合 [409600, 927408] 的区间要求。 大小：单个视频不超过 50 MB。 帧率 (FPS)：[24, 60] |
| `reference_audio_urls` | Yes | 单个音频要求: 格式：wav、mp3 时长：单个音频时长 [2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15 s。 大小：单个音频不超过 15 MB。 |
| `resolution` | Yes | 视频分辨率 - 480p 生成速度更快，720p 兼顾速度与画质 Allowed values: 480p 720p Default: 720p Example: 720p |
| `aspect_ratio` | Yes | 视频画面比例配置。必填字段。 Allowed values: 1:1 4:3 3:4 16:9 9:16 21:9 adaptive Default: 16:9 Example: 16:9 |
| `duration` | Yes | 视频时长4-15（秒）。 |
| `web_search` | Yes | 是否启用联网搜索 |
| `callBackUrl` | No | 接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/video/seedancevtpf?key=你的密钥
```

## Details

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| key | 是 | string | 35kj5jnlj53453kl5j43nj5 | 接口密钥,在控制台->密钥管理查看 |
| prompt | 是 | string |  一个宁静的海滩在日落时分，海浪轻轻拍打着海岸，棕榈树随风摇曳，海鸥在橙色天空中飞翔。 | 用于生成视频的文本提示词。(最大长度:30000个字符) |
| callBackUrl | 是 | string | https://your-domain.com/api/callback | 回调地址，接收生成任务完成更新的URL。但推荐用于生产环境使用。当生成完成后，系统将向此URL发送任务状态和结果的POST请求。 |
| first_frame_url | 否 | string | http:://asset.cn/asset-20260404242101-76d.jpg | 第一帧图像URL或资产路径，不能与reference_image_urls, reference_video_urls或reference_audio_urls同时使用。 |
| last_frame_url | 否 | string | http:://asset.cn/asset-20260404242102-76d.jpg | 结束帧图像URL或资产,最后帧URL不能单独传递;必须与第一个帧URL一起提供。 |
| reference_image_urls | 否 | array[string] | ["https://file.aiquickdraw.com/example1.png"] | 参考图像URL列表, 支持 ≤30 张图片，最大 30M; 格式:jpeg、png、webp、bmp、tiff、gif。宽高比(宽度/高度):(0.4,2.5)宽度和高度(像素):(300,6000); 与首帧/末帧场景互斥。 |
| reference_video_urls | 否 | array[string] | ["https://file.aiquickdraw.com/example1.mp4"] | 参考视频URL列表, 支持 ≤10 个视频，最长 30 秒;视频格式:mp4、mov,分辨率:480p，720p, 宽高比(宽度/高度):[0.4,2.5],宽高(像素):[300,6000],总像素:[640X640=409600，834X1112=9274083]，即宽度和高度的乘积必须满足范围要求[409600,927408]。大小:单个视频不超过200MB。帧率(FPS):[24,60]单个视频时长:[2,30]秒;与首帧/末帧场景互斥;参考视频总时长不得超过30秒。 |
| reference_audio_urls | 否 | array[string] | ["https://file.aiquickdraw.com/example1.wav"] | 参考音频URL列表, 支持 ≤10 个音频，最长 30 秒;格式:wav、mp3;大小:单个音频文件大小不超过15MB;单个音频时长:[2,30]秒;与首帧/末帧场景互斥;参考音频的总时长不得超过30秒。 |
| generate_audio | 否 | boolean | true | 是否为视频生成音频。true:生成带音频, false:不生成音频, 注意:默认true。 |
| resolution | 否 | string | 720p | 生成视频的分辨率，视频分辨率-480p用于更快生成，720p用于平衡。允许的值:480p、720p, 注意:默认720p。 |
| aspect_ratio | 否 | string | 16:9 | 生成视频的宽高比，视频宽高比配置。允许的值:1:1、4:3、3:4、16:9、9:16、adaptive(自适应)、21:9；默认值:16:9。 |
| duration | 否 | int | 10 | 生成视频的时长，视频时长在4到30秒之间；注意:默认15, 将参数设为-1以启用自动持续时间选择——模型会自行选择合适的持续时间（对于视频编辑任务，它会匹配输入视频的长度；对于其他任务类型，它会从有效范围内进行选择），而无需您指定确切的值。 |
| web_search | 否 | boolean | false | 是否启用在线搜索；注意:默认false。 |
| nsfw_checker | 否 | boolean | true | 是否启用NSFW检查器；注意:默认true。 |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 状态码 |
| msg | string | 状态信息 |
| data | string | 请求结果数据集 |
| -- task_id | string | 任务 ID 可以查询任务状态 |
| debug | string/array | 调试数据 |
| exec_time | float | 执行耗时 |
| user_ip | string | 客户端IP |

## Error Codes

| Status / code | Description |
|---------------|-------------|
| 200 / success | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed, please check API Key |
| 402 | Insufficient account balance / points |
| 429 | Request rate limit exceeded |
| 500 | Internal server error |

## Usage Flow

1. **Create Task**: Call this API with your `key` and required parameters
2. **Get Task ID**: Read the task id from the response
3. **Wait for Results**: Use the notify/callback URL if provided, or poll the related query endpoint
4. **Get Results**: When the task succeeds, read result URLs / payload from the response

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._