Seedance 2.0 视频生成 API 文档

接口说明

创建和轮询接口均不支持免费试用：必须提供创建该任务时使用的有效本项目 API Key。服务端固定使用 doubao-seedance-2-0-260128，调用方无需也不能指定 model。创建后只需使用返回的 task_id 调用同一个查询接口；服务端自动完成 Redis 排队、上游提交、callback 回写与轮询兜底。可选 callback_url 必须是公开 HTTPS 地址；设置后本响应仅一次返回 callback_secret。终态投递 JSON 并带 X-Seedance-Task-Id、X-Seedance-Timestamp、X-Seedance-Signature: sha256=<HMAC-SHA256 原始请求体>；接收端须在 10 秒内返回 2xx，失败最多重试三次。

任务生命周期与排障

创建任务：调用本接口后立即取得唯一 task_id；服务端将任务写入 Redis 队列并预扣积分。
统一查询：POST /volcengine/contents/generations/tasks/query，请求体传 task_id 和 api_key。queued/submitting 表示服务端正在排队；submitted/running 表示上游生成中；成功直接返回视频，失败直接返回原因。
服务端完成上游流程：worker 自动提交上游并附加 callback_url；火山回调优先写入结果，worker 轮询作为回调延迟或丢失时的兜底。
查看终态与结算：成功时从 data.result.content.video_url 读取视频；失败时查看 data.reason；服务端按 completion_tokens 对 200 积分预扣多退少补。
定位常见失败：素材不可访问会在创建前返回位置和原因；上游资源/参数错误会出现在 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	否	上游工具配置，原样透传	`[]`
`callback_url`	string	否	终态用户回调地址；必须为公开 HTTPS URL。创建响应仅一次返回 callback_secret，用于 HMAC-SHA256 验签	`https://client.example/seedance/callback`

调用示例

创建文生视频任务

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/tasks/query" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "<job_id>",
    "api_key": "uk_live_xxx"
  }'

返回参数

字段路径	类型	说明
`code`	number	本地业务状态码，200 表示请求已成功转发并收到上游响应
`msg`	string	创建时为“创建视频生成任务成功”；查询时为“查询视频生成任务成功”
`data.task_id`	string	创建响应返回的唯一公共任务标识，用于统一查询接口
`data.status`	string	queued、submitting、submitted、succeeded、failed 或 submit_unknown
`data.result`	object	服务端保存的最新上游结果；成功时含 content.video_url
`settlement.status`	string	仅成功且已返回用量的任务出现：charged 表示已结算，outstanding 表示视频已返回但仍有欠费，pending 表示正在结算
`settlement.credits`	number	该成功任务的最终扣除积分
`data.url`	string \| null	素材校验失败时返回：不可访问素材的链接（已移除查询参数、片段和凭据）
`data.callback_secret`	string	仅设置 callback_url 时返回一次；服务端不再提供该值，务必安全保存

返回示例

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

用户 Callback 接入规范

创建请求传入 callback_url 后，创建响应只会返回一次 callback_secret。终态回调仅在成功或失败时投递；查询接口仍可作为可靠兜底。

服务端投递方式

方法	`POST`
Content-Type	`application/json`
成功标准	接收端在 10 秒内返回任意 `2xx`。响应体可为空；网络错误、超时或非 2xx 最多重试 3 次。
`X-Seedance-Task-Id`	创建响应中的唯一 task_id。
`X-Seedance-Timestamp`	ISO 8601 投递时间。
`X-Seedance-Signature`	sha256=<hex>；使用 callback_secret 对原始 JSON 请求 body 计算 HMAC-SHA256。

终态事件：成功示例

{
  "event": "seedance.task.completed",
  "task_id": "task_xxx",
  "status": "succeeded",
  "result": {
    "content": {
      "video_url": "https://example.com/generated-video.mp4"
    }
  },
  "error": null,
  "settlement": {
    "status": "settled",
    "credits": 200,
    "actualCredits": 43
  },
  "completed_at": "2026-07-23T04:00:00.000Z"
}

终态事件：失败示例

{
  "event": "seedance.task.completed",
  "task_id": "task_xxx",
  "status": "failed",
  "result": null,
  "error": "上游任务失败：素材不可访问",
  "settlement": {
    "status": "settled",
    "credits": 200,
    "actualCredits": null
  },
  "completed_at": "2026-07-23T04:00:00.000Z"
}

Node.js 验签与接收示例

import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.use(express.raw({ type: 'application/json' }));
app.post('/seedance/callback', (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.SEEDANCE_CALLBACK_SECRET).update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Seedance-Signature') || ''))) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  // 按 event.task_id 幂等保存终态结果
  return res.status(200).json({ received: true }); // 任意 2xx 均视为投递成功
});