Seedance 2.0 视频生成 API 文档

接口说明

创建和轮询接口均不支持免费试用：必须提供创建该任务时使用的有效本项目 API Key。服务端固定使用 doubao-seedance-2-0-260128，调用方无需也不能指定 model。创建接口立即返回 job_id；使用 POST /volcengine/contents/generations/jobs/query 查询本地排队状态，收到 task_id 后再调用 POST /volcengine/contents/generations/tasks/query 获取视频结果。创建任务前，所有图片、视频和音频参考链接都会验证为可公开访问的 HTTP(S) 媒体；不可访问、非公开网络地址、重定向异常或类型不匹配会被拒绝并返回素材位置、链接和原因。

任务生命周期与排障

创建本地 job：调用本接口后立即取得 job_id；这就是 trace_id，不代表上游 task 已创建。
第一阶段轮询（必调）：POST /volcengine/contents/generations/jobs/query，请求体传 job_id 和 api_key；持续查询至返回 task_id。
第二阶段轮询（必调）：仅在 jobs/query 返回 task_id 后，POST /volcengine/contents/generations/tasks/query，请求体传 task_id 和 api_key；持续查询至 succeeded 或 failed。
查看终态：成功时从 data.content.video_url 读取视频；failed 时查看 data.error；submit_unknown 表示提交超时或网络中断，系统不会自动重试。
定位常见失败：素材不可访问会在创建前返回位置和原因；上游资源/参数错误会出现在 job reason；输出音频敏感会在 task 的 data.error 返回。

按 trace 检索日志

docker logs --since 1h coze-js-api-app-blue-1 2>&1 | rg '"trace_id":"<job_id>"'
docker logs --since 1h coze-js-api-seedance-worker-1 2>&1 | rg '"trace_id":"<job_id>"'

打开交互式 Trace 流程演示 →

请求参数

字段	类型	必填	说明	示例
`api_key`	string	是	本项目付费 API Key；不支持免费试用，创建任务前校验有效性和可用积分	`uk_live_xxx`
`content`	array \| JSON string	是	输入内容；至少包含文本，可按需加入参考图、参考视频或参考音频	`[{"type":"text","text":"..."}]`
`content[].type`	string	是	内容类型，如 text、image_url、video_url、audio_url	`text`
`content[].role`	string	否	参考媒体角色，例如 first_frame、reference_image、reference_video、reference_audio	`first_frame`
`content[].<media>.url`	string	是	公开可访问的 HTTP(S) 素材链接；创建前会检测可访问性和媒体类型，不通过时不会调用上游	`https://example.com/first-frame.png`
`generate_audio`	boolean	否	是否生成音频，按上游模型能力处理	`true`
`resolution`	string	否	目标分辨率，按模型支持的枚举传入	`720p`
`ratio`	string	否	画面比例，按模型支持的枚举传入	`16:9`
`duration`	number	否	视频时长，按模型支持范围传入	`5`
`watermark`	boolean	否	是否添加水印	`false`
`tools`	array \| JSON string	否	上游工具配置，原样透传	`[]`

调用示例

创建文生视频任务

curl -X POST "https://coze-js-api.devtool.uk/volcengine/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "uk_live_xxx",
    "content": [
      {
        "type": "text",
        "text": "一只猫在雨夜的霓虹街道上缓慢行走，镜头轻微跟随，氛围电影感。"
      }
    ],
    "generate_audio": true,
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

创建带首帧参考图的视频任务

curl -X POST "https://coze-js-api.devtool.uk/volcengine/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "uk_live_xxx",
    "content": [
      {
        "type": "text",
        "text": "让画面中的人物自然向前行走，保持首帧构图和服装风格。"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first-frame.png" },
        "role": "first_frame"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

查询排队任务，获取 task_id

curl -X POST "https://coze-js-api.devtool.uk/volcengine/contents/generations/jobs/query" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "<job_id>",
    "api_key": "uk_live_xxx"
  }'

返回参数

字段路径	类型	说明
`code`	number	本地业务状态码，200 表示请求已成功转发并收到上游响应
`msg`	string	创建时为“创建视频生成任务成功”；查询时为“查询视频生成任务成功”
`data.job_id`	string	创建响应返回的本地排队任务标识，用于 jobs/query
`data.status`	string	queued、submitting、submitted、succeeded、failed 或 submit_unknown
`data.task_id`	string \| null	worker 成功提交上游后返回；用于 tasks/query
`settlement.status`	string	仅成功且已返回用量的任务出现：charged 表示已结算，outstanding 表示视频已返回但仍有欠费，pending 表示正在结算
`settlement.credits`	number	该成功任务的最终扣除积分
`data.url`	string \| null	素材校验失败时返回：不可访问素材的链接（已移除查询参数、片段和凭据）

返回示例

{
  "code": 200,
  "msg": "视频生成任务已进入队列",
  "data": {
    "job_id": "job_xxx",
    "status": "queued",
    "task_id": null
  }
}