视频生成（Seedance）

本文档面向接入方，说明如何调用统一视频生成接口（Seedance 系列模型，如 doubao-seedance-2.0）。

接口概览

创建视频生成任务

POST /v1/videos/generations
兼容别名：POST /v1/video/generations

查询视频生成任务

GET /v1/videos/generations/{task_id}
兼容别名：GET /v1/video/generations/{task_id}

认证方式

通过 Authorization 请求头传入 API Key：

http

Authorization: Bearer sk-xxxxxx

创建任务

请求头

http

Content-Type: application/json
Accept: application/json
Authorization: Bearer sk-xxxxxx

请求体

json

{
  "model": "doubao-seedance-2.0",
  "prompt": "一只猫在海边奔跑，电影感，夕阳，4k",
  "mode": "pro",
  "input_type": "text_to_video",
  "images": [],
  "videos": [],
  "audios": [],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "metadata": {
    "draft": false,
    "generate_audio": false,
    "watermark": false
  }
}

成功响应示例

json

{
  "id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "task_id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "object": "video.generation.task",
  "status": "submitted",
  "message": "task submitted"
}

说明：

创建接口只表示任务已提交。
大多数异步视频任务在创建时不会立即返回最终视频结果。
最终结果需要通过查询接口获取。

查询任务

请求示例

bash

curl --request GET \
  --url 'https://bigbangtoken.com/v1/videos/generations/task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg' \
  --header 'Authorization: Bearer sk-xxxxxx' \
  --header 'Accept: application/json'

成功响应示例

json

{
  "id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "task_id": "task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg",
  "object": "video.generation.task",
  "status": "succeeded",
  "message": "task completed",
  "trace_id": "trace_xxx",
  "data": [
    {
      "url": "https://example.com/output.mp4"
    }
  ],
  "video_url": "https://example.com/output.mp4",
  "duration": 5,
  "usage": {
    "completion_tokens": 108000,
    "total_tokens": 108000
  }
}

失败响应示例

json

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.task",
  "status": "failed",
  "message": "task failed",
  "error": {
    "message": "provider returned an error",
    "code": "provider_error"
  }
}

请求参数

顶层字段

字段	类型	必填	说明
`model`	`string`	是	模型名称，例如 `doubao-seedance-2.0`
`prompt`	`string`	是	文本提示词
`mode`	`string`	否	生成模式，例如 `pro`、`fast`。是否生效取决于模型和上游
`input_type`	`string`	否	输入类型，例如 `text_to_video`、`first_last_frame`、`reference`
`image`	`string`	否	单图兼容字段。传单张图片时可使用；服务端会自动转成 `images[0]`
`images`	`string[]`	否	图片输入 URL 数组
`videos`	`string[]`	否	视频输入 URL 数组
`audios`	`string[]`	否	音频输入 URL 数组
`resolution`	`string`	否	输出分辨率，例如 `480p`、`720p`、`1080p`
`ratio`	`string`	否	宽高比，例如 `16:9`、`9:16`、`1:1`
`size`	`string`	否	兼容字段，部分模型使用显式尺寸，如 `1280x720`
`duration`	`number` / `string`	否	输出视频时长，单位秒。推荐传整数，例如 `5`
`seconds`	`string`	否	兼容字段，与 `duration` 语义相同
`metadata`	`object` / `string`	否	上游扩展参数。可传对象，也可传 JSON 字符串

`metadata` 常见字段

metadata 用于透传上游附加参数。不同上游支持项不同，常见字段如下：

字段	类型	说明
`draft`	`boolean`	是否启用样片模式
`generate_audio`	`boolean`	是否生成同步音频
`watermark`	`boolean`	是否添加水印
`return_last_frame`	`boolean`	是否返回尾帧
`callback_url`	`string`	任务完成后的回调地址
`seed`	`number`	随机种子
`execution_expires_after`	`number`	任务超时时间，单位秒
`safety_identifier`	`string`	终端用户唯一标识
`tools`	`object` / `array`	工具配置，由具体上游定义

说明：

metadata 中未被平台显式消费的字段，会尽量原样透传给上游。
某些字段即使能传，也可能因当前通道或模型不支持而被上游忽略或拒绝。

输入类型说明

1. 文生视频

适合纯文本生成视频。

json

{
  "model": "doubao-seedance-2.0",
  "prompt": "一只猫在海边奔跑，电影感，夕阳，4k",
  "input_type": "text_to_video",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

2. 首尾帧生成

适合提供首帧和尾帧图片，让模型生成中间动态过程。

json

{
  "model": "doubao-seedance-2.0",
  "prompt": "镜头平滑推进，角色从静止到转身",
  "input_type": "first_last_frame",
  "images": [
    "https://example.com/frame-start.png",
    "https://example.com/frame-end.png"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

说明：

first_last_frame 通常要求 images 至少包含 2 张图。
具体张数限制由模型和上游决定。

3. 参考图生成

适合用一张或多张参考图控制主体、风格或构图。

json

{
  "model": "doubao-seedance-2.0",
  "prompt": "角色保持一致，镜头环绕，电影感",
  "input_type": "reference",
  "images": [
    "https://example.com/reference-1.jpg"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

4. 参考视频生成

适合基于已有视频进行视频再生成、延展或风格变化。

json

{
  "model": "doubao-seedance-2.0",
  "prompt": "保留主体动作，整体改成赛博朋克氛围",
  "input_type": "reference",
  "videos": [
    "https://example.com/reference.mp4"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

说明：

是否支持视频输入，取决于模型和通道。
视频输入通常会影响最终计费。

5. 参考音频生成

适合携带音频输入的任务。

json

{
  "model": "doubao-seedance-1.5-pro",
  "prompt": "角色跟随音乐节奏移动，镜头稳定推进",
  "input_type": "reference",
  "audios": [
    "https://example.com/reference.wav"
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "metadata": {
    "generate_audio": true
  }
}

字段兼容规则

`image` 与 `images`

推荐使用 images
如果只传单张图片，也可以使用 image
服务端会将 image 自动视为 images[0]

`duration` 与 `seconds`

推荐使用 duration
seconds 为兼容旧客户端保留
如果两者同时存在，最终解释以服务端实际解析结果为准，建议不要同时传

`metadata`

支持对象：

json

"metadata": {
  "draft": true,
  "watermark": false
}

也支持 JSON 字符串：

json

"metadata": "{\"draft\":true,\"watermark\":false}"

任务状态

统一返回以下状态之一：

状态	说明
`pending`	已创建，等待提交或上游尚未确认
`submitted`	已提交到上游
`running`	正在生成
`succeeded`	生成成功
`failed`	生成失败

返回字段说明

创建任务响应

字段	类型	说明
`id`	`string`	公有任务 ID
`task_id`	`string`	与 `id` 等价，兼容字段
`object`	`string`	固定为 `video.generation.task`
`status`	`string`	当前任务状态
`message`	`string`	状态说明

查询任务响应

字段	类型	说明
`id`	`string`	公有任务 ID
`task_id`	`string`	与 `id` 等价
`object`	`string`	固定为 `video.generation.task`
`status`	`string`	当前任务状态
`message`	`string`	状态说明
`trace_id`	`string`	上游追踪 ID，可能为空
`data`	`array`	视频结果数组，成功时通常包含至少一个对象
`data[].url`	`string`	生成结果视频地址
`video_url`	`string`	主视频地址，通常与 `data[0].url` 一致
`duration`	`number`	输出视频时长
`usage.completion_tokens`	`number`	上游返回的实际消耗 token
`usage.total_tokens`	`number`	上游返回的总 token
`error.message`	`string`	失败原因
`error.code`	`string`	失败代码

计费说明

对于异步视频任务：

提交任务时，系统可能先执行预扣。
任务完成后，最终费用以查询结果中的 usage.completion_tokens 为准重新结算。
如果最终应扣低于预扣，会退款。
如果最终应扣高于预扣，会补扣。

建议调用方在业务上区分：

创建成功：表示任务受理成功
查询成功且 status = succeeded：表示生成成功
查询结果中出现 usage.completion_tokens：表示已经进入最终计费口径

错误响应

统一错误格式示例：

json

{
  "error": {
    "message": "task_id is required",
    "type": "invalid_request_error",
    "param": "",
    "code": ""
  }
}

常见错误场景：

场景	说明
`401 Unauthorized`	API Key 无效或缺失
`403 Forbidden`	当前令牌无权限使用该模型或通道
`400 Invalid Request`	参数缺失、格式错误或模型不支持该组合
`404 Not Found`	`task_id` 不存在或不属于当前用户
`500 Internal Server Error`	服务端异常或上游异常

最佳实践

1. 先创建，再轮询查询

推荐流程：

调用创建接口获取 task_id
每隔 2 到 5 秒调用查询接口
直到状态变为：
- succeeded
- failed

2. 统一使用 URL 资源

推荐为图片、视频、音频提供公网可访问 URL，例如：

https://example.com/input.jpg
https://example.com/input.mp4
https://example.com/input.wav

3. 不要混用兼容字段

例如：

不要同时传 image 和 images
不要同时传 duration 和 seconds

4. 先按模型能力做参数校验

不同模型对以下能力支持不同：

是否支持图片输入
是否支持视频输入
是否支持音频输入
是否支持 1080p
是否支持样片模式
是否支持同步音频

建议在业务侧按模型能力限制参数组合，避免无效请求。

cURL 示例

文生视频

bash

curl --request POST \
  --url 'https://bigbangtoken.com/v1/videos/generations' \
  --header 'Authorization: Bearer sk-xxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-2.0",
    "prompt": "一只猫在海边奔跑，电影感，夕阳，4k",
    "input_type": "text_to_video",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "metadata": {
      "draft": false,
      "generate_audio": false,
      "watermark": false
    }
  }'

参考图视频

bash

curl --request POST \
  --url 'https://bigbangtoken.com/v1/videos/generations' \
  --header 'Authorization: Bearer sk-xxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-2.0",
    "prompt": "角色保持一致，镜头环绕，电影感",
    "input_type": "reference",
    "images": [
      "https://example.com/reference-1.jpg"
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

查询任务

bash

curl --request GET \
  --url 'https://bigbangtoken.com/v1/videos/generations/task_65RmeonGhUJrizaVkQzAauwIXdOA1YFg' \
  --header 'Authorization: Bearer sk-xxxxxx'

视频生成（Seedance） ​

接口概览 ​

创建视频生成任务 ​

查询视频生成任务 ​

认证方式 ​

创建任务 ​

请求头 ​

请求体 ​

成功响应示例 ​

查询任务 ​

请求示例 ​

成功响应示例 ​

失败响应示例 ​

请求参数 ​

顶层字段 ​

metadata 常见字段 ​

输入类型说明 ​

1. 文生视频 ​

2. 首尾帧生成 ​

3. 参考图生成 ​

4. 参考视频生成 ​

5. 参考音频生成 ​

字段兼容规则 ​

image 与 images ​

duration 与 seconds ​

metadata ​

任务状态 ​

返回字段说明 ​

创建任务响应 ​

查询任务响应 ​

计费说明 ​

错误响应 ​

最佳实践 ​

1. 先创建，再轮询查询 ​

2. 统一使用 URL 资源 ​

3. 不要混用兼容字段 ​

4. 先按模型能力做参数校验 ​

cURL 示例 ​

文生视频 ​

参考图视频 ​

查询任务 ​

视频生成（Seedance）

接口概览

创建视频生成任务

查询视频生成任务

认证方式

创建任务

请求头

请求体

成功响应示例

查询任务

请求示例

成功响应示例

失败响应示例

请求参数

顶层字段

`metadata` 常见字段

输入类型说明

1. 文生视频

2. 首尾帧生成

3. 参考图生成

4. 参考视频生成

5. 参考音频生成

字段兼容规则

`image` 与 `images`

`duration` 与 `seconds`

`metadata`

任务状态

返回字段说明

创建任务响应

查询任务响应

计费说明

错误响应

最佳实践

1. 先创建，再轮询查询

2. 统一使用 URL 资源

3. 不要混用兼容字段

4. 先按模型能力做参数校验

cURL 示例

文生视频

参考图视频

查询任务