Seedance 生视频接口接入说明

视频任务创建与查询

1. 概述

本接口用于异步创建视频生成任务，并查询任务状态和生成结果，支持文生视频、图生视频与多模态参考生视频。

  • 创建任务：POST {baseUrl}/video/generations/{apiType}
  • 查询任务：POST {baseUrl}/video/resource-actions/{apiType}

2. 接入前置条件

项 说明
api_key 访问密钥（控制台生成），用于 Bearer 鉴权。
model 已在平台开通的爱诗视频模型编码。
model 已在平台开通的视频模型编码。

3. 鉴权

HTTP 
Authorization: Bearer <api_key>
Content-Type: application/json
Accept: application/json

4. 创建视频任务

POST {baseUrl}/video/generations/{apiType}

4.1 {apiType} 枚举说明

{apiType} 区分大小写，且必须与访问的接口路径匹配。

接口 {apiType} 值 说明
创建视频任务 TextToVideo 创建异步视频生成任务，支持文生视频、图生视频及多模态参考生视频。
查询视频任务 QueryVideo 查询已创建视频任务的状态与结果。

4.2 请求参数

字段 类型 必填 说明
model string 是 平台已开通的视频模型编码。
content array 二选一 输入内容片段数组；与 messages 二选一，至少传入其中一项。
messages array 二选一 消息数组，用于传入文本或多模态内容；与 content 二选一，至少传入其中一项。
ratio enum 否 输出宽高比：16:9/4:3/1:1/3:4/9:16/21:9/adaptive
duration integer 否 生成时长（秒）；Seedance 2.0 为 4–15 或 -1，2.5 为 4–30 或 -1
frames integer 否 生成帧数；与 duration 二选一，frames 优先；2.5 不支持
resolution enum 否 分辨率：480p/720p/1080p/4k；默认 720p
seed integer 否 随机种子，范围 [-1, 2^32-1]，-1 为随机；2.5 不支持
camera_fixed boolean 否 是否固定摄像头视角；2.0/2.5 不支持
watermark boolean 否 是否包含水印，默认 false
generate_audio boolean 否 是否生成同步音频，默认 true
return_last_frame boolean 否 是否返回尾帧 PNG，用于多段衔接，默认 false
callback_url string 否 任务状态变更回调地址
service_tier enum 否 default（在线推理）/ flex（离线推理）；2.0/2.5 不支持 flex
output_format enum 否 输出封装格式：mp4/mov；仅 2.5 支持
priority integer 否 队列优先级 [0, 9]；2.0/2.5 支持
execution_expires_after integer 否 任务过期时间（秒），范围 [3600, 259200]，默认 172800
auto_create_assets boolean 否 自动创建临时素材并审核
omni_reference_task_type enum 否 2.5 全模态参考任务类型：auto/reference/edit/extend
draft boolean 否 是否开启样片模式；仅 1.5 pro 支持
tools array 否 模型工具配置（如联网搜索）
safety_identifier string 否 终端用户标识（建议哈希，≤64 字符）

4.3 content / messages 片段结构

content 与 messages[].content 均可承载下列多模态片段；每个片段的 type 决定其结构：

type 必填字段 说明
text text 文本提示词；建议中文 ≤500 字、英文 ≤1000 词
image_url image_url.url；image_url.role（首帧/首尾帧必填） 图片输入；role 为 first_frame/last_frame/reference_image
video_url video_url.url、video_url.role 视频参考；role 为 reference_video；支持公网 URL 或 asset://
audio_url audio_url.url、audio_url.role 音频参考；role 为 reference_audio；支持 URL、data:audio/<fmt>;base64,... 或 asset://
draft_task draft_task.id 样片任务引用；仅 1.5 pro

4.4 模型能力对照

能力 Seedance 2.5 Seedance 2.0 标准版 Seedance 2.0 Fast / Mini
最高分辨率 720p 4K 720p
最长输出 30 秒 15 秒 15 秒
输出格式 MP4、MOV MP4 MP4
纯音频参考 支持 不支持 不支持
参考图片上限 30 9 9
参考视频/音频上限 各 10 各 3 各 3
素材总上限 50 12 12

4.5 文生视频示例

JSON 
{
  "model": "bytedance/doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "夕阳下的城市街道，电影感镜头缓慢推进"}
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

4.6 图生视频示例（首帧）

JSON 
{
  "model": "bytedance/doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "一只金毛犬在海边奔跑，电影感镜头"},
    {"type": "image_url", "image_url": {"url": "https://example.com/dog.jpg", "role": "first_frame"}}
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

4.7 messages 示例

JSON 
{
  "model": "bytedance/doubao-seedance-2-0-260128",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "一只金毛犬在海边奔跑，电影感镜头"},
      {"type": "image", "fileUrl": {"url": "https://example.com/dog.jpg"}}
    ]
  }],
  "duration": 5,
  "resolution": "720p"
}

4.8 创建响应

创建成功后返回任务 ID：

JSON 
{
  "id": "qvideo-xxxxxxxxxxxxxxxx"
}

读取根级 id 作为后续查询的 taskId。

5. 查询视频任务

POST {baseUrl}/video/resource-actions/{apiType}

使用 QueryVideo 查询视频生成任务的状态与结果。

5.1 请求参数

字段 类型 必填 说明
model string 是 平台 ag_model 配置的模型编码
taskId string 是 创建任务返回的 id；也接受 task_id 或 id 字段名
JSON 
{
  "model": "bytedance/doubao-seedance-2-0-260128",
  "taskId": "qvideo-xxxxxxxxxxxxxxxx"
}

5.2 查询响应

查询成功后返回任务状态和结果资源。常用字段如下：

字段 说明
id 任务 ID
model 模型名称-版本
status 任务状态：queued/running/succeeded/failed/cancelled/expired
error 失败时的错误对象（code+message）；成功时为 null
created_at 创建时间戳（秒）
updated_at 状态更新时间戳（秒）
content.video_url 生成视频 MP4 地址；约 24 小时后清理
content.last_frame_url 尾帧图 URL；return_last_frame=true 时返回
usage.completion_tokens 输出 token 数
usage.total_tokens 总 token（通常等于 completion_tokens）
resolution / ratio / duration / frames / framespersecond 视频属性

成功响应示例（Seedance 2.0）：

JSON 
{
  "id": "qvideo-xxxxx-1775645542150946615",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "succeeded",
  "created_at": 1775645542,
  "updated_at": 1775646115,
  "content": {
    "video_url": "https://aitoken-video.qnaigc.com/xxxxxxxx"
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 11,
  "usage": {
    "completion_tokens": 411300,
    "total_tokens": 411300
  },
  "service_tier": "default",
  "framespersecond": 24,
  "execution_expires_after": 172800
}

6. 响应与轮询

  • 创建：保留根级 id，用于后续查询。
  • 查询：响应包含任务状态、结果资源和 usage 等字段。
  • 轮询建议：间隔 3～5 秒，在终态（succeeded/failed/cancelled/expired）后停止。
  • 计费：仅终态 succeeded 且响应包含有效 usage 时，该 usage 才是本任务的最终用量依据；失败、取消或未返回 usage 的任务不应按最终用量结算。
  • 结果转存：content.video_url 约 24 小时后清理，请及时下载或转存。