视频与素材

创建任务(火山兼容)

通过火山兼容格式创建 Seedance 任务。

POST
/api/v3/contents/generations/tasks

概览

已有火山风格 Seedance 客户端只需更换 API 地址和密钥,即可通过 TokenLab 创建任务。

本页示例使用 Seedance 2.0;该接口也支持 Seedance 2.5,模型间差异见下文。 本页的可复用 TokenLab 素材 URI 用法适用于 Seedance 2.0。

另见 Seedance 2.0 视频模型 和 视频生成。

鉴权与入口

  • 使用 Authorization: Bearer <TOKENLAB_API_KEY>。
  • 不接受火山 AK/SK 签名。请求必须携带 TokenLab Bearer 密钥。
  • 使用官方任务路径:POST /api/v3/contents/generations/tasks。

内容规则

  • type: "text" 表示提示词文本。
  • type: "image_url" 不传 role 或传 role: "first_frame" 时按首帧处理。
  • role: "last_frame" 必须和首帧一起使用。
  • type: "video_url" 必须使用 role: "reference_video",type: "audio_url" 必须使用 role: "reference_audio";role: "reference_image" 表示参考图。
  • 条目上限:Seedance 2.0 最多 16 个 content 条目(文本 1、图片 9、视频 3、音频 3、draft_task 1);Seedance 2.5 最多 51 个(文本 1、图片 30、视频 10、音频 10、draft_task 1)。
  • image_url.url 可以是公网图片 URL,也可以是 asset://asset-YYYYMMDDHHMMSS-xxxxx 形式的 TokenLab 素材 URI;role 决定该素材是首帧、尾帧还是参考图。
  • 同一个请求里不要混用首尾帧输入和参考素材。
  • REST 请求体只接受本页列出的字段。其他顶层字段(包括 material_asset_id 和 material_asset_ids)会返回 400 UnsupportedParameter。请将 TokenLab 素材 URI 放入 image_url.url。

参数说明

model 可以填写 TokenLab 模型 ID,例如 seedance-2.0 或 seedance-2.5。已有客户端也可以继续发送这些模型已在使用的火山引擎模型 ID。查询任务返回的 model 与你发送的值一致。无法识别的值返回 400 InvalidParameter。

duration 为整数秒数,-1 表示自动时长。默认值和限制因模型而异:

参数Seedance 2.0Seedance 2.5
duration4–15 / -1 (默认: 5)4–30 / -1 (默认: -1)
resolution480p, 720p, 1080p (默认: 720p)480p, 720p (默认: 720p)
generate_audioboolean (默认: false)boolean (默认: true)
priority不支持integer: 0–9
seedinteger: -1–4294967295 (默认: -1)不支持
execution_expires_after3600–259200 秒 (默认: 172800)3600–259200 秒 (默认: 172800)

Seedance 2.5 的首帧、首尾帧、视频延长和视频到视频请求必须使用 ratio: "adaptive";视频到视频还必须使用 duration: -1。output_format 的 mp4 和 mov 选项仅 Seedance 2.5 支持。

  • ratio 支持 16:9、4:3、1:1、3:4、9:16、21:9 或 adaptive(默认 adaptive)。
  • watermark 和 return_last_frame 为布尔值(默认 false)。safety_identifier 是最长 64 个字符的字符串。
  • service_tier 只接受 default;flex 会返回 400 UnsupportedParameter。
  • tools 最多一项,即 {"type": "web_search"}。
  • 不支持 draft: true、frames 和 camera_fixed;仅 Seedance 2.0 接受 camera_fixed: false。
  • callback_url 可填写公网 HTTP(S) 地址,最长 2,048 个字符。

Callback 回调

传入 callback_url 后,任务状态变化时 TokenLab 会发送 HTTP POST。回调状态包括 queued、running、succeeded、failed 和 expired,JSON body 与查询任务接口返回的任务对象一致。

接收端返回任意 2xx 即视为送达。succeeded 和 failed 回调在五秒内未送达时最多重试三次。回调不会跟随重定向,也不接受内网或保留地址。

请保存任务 ID。回调未送达时,仍可通过查询任务接口获取结果。

图片准备

公网 HTTP(S) 图片 URL 和受支持的 data URL 按输入使用,不会自动保存为可复用素材。显式 asset://asset-... 引用使用已有 TokenLab 素材,生成前会检查归属与就绪状态。如果引用的素材仍在准备,请等待就绪后重试;创建失败时查看 error.code 和 error.message。

使用已有 TokenLab 素材时,请传 asset-YYYYMMDDHHMMSS-xxxxx ID。

创建响应

{
  "id": "cgt-20260102030405-a1b2c"
}

创建响应只包含任务 ID。请保存它,以便随时查询状态和结果。

避免重复创建

创建请求建议携带唯一的 Idempotency-Key(1–255 个字符,不含换行)。如果连接在响应返回前中断,请使用同一枚 API 密钥、同一个 key 和相同的请求体重试:

  • 任务已经创建时,返回相同的 cgt-... ID,并附带 Idempotency-Replayed: true。
  • 同一个 key 配不同请求体时返回 409,错误码为 idempotency_conflict,不会再创建第二个任务。
  • key 超过 255 个字符或含换行时返回 400 InvalidParameter。

Idempotency-Key 不会改变 JSON 响应结构。X-Request-ID 或不带 key 的相同请求体不会被当作重复请求。

示例

REST 创建

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

使用已有素材时,请把每个素材 URI 放进官方 content[] 结构并明确用途:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

错误

REST 错误格式为 {"error": {"code", "message", "param", "type"}}。请求问题返回 400,错误码为 InvalidParameter 或 UnsupportedParameter;缺少 Bearer 密钥返回 401 AuthenticationError。视频生成产生的错误(例如余额不足 402、触发限流 429)保持原 HTTP 状态码。

同样的操作也可以通过 POST /api/v3?Version=2024-01-01 的 CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks 和 DeleteContentsGenerationsTasks Action 调用。新集成请使用上面的 REST 路径。

查询结果

使用返回的 cgt-... ID 调用 查询任务(火山兼容)。

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'
{  "id": "string"}

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

客户端生成的用于幂等 REST 任务创建的 key,1-255 个字符,不含换行符。在相同的 TokenLab API 凭据下,使用相同的 key 和相同的 JSON 正文重试将返回原始的 cgt 任务 ID;使用不同的正文重试将返回 409 以及 idempotency_conflict 代码。过长或包含换行符的 key 将返回 400。在超时或断开连接后重试时,请保持凭据、key 和请求正文不变。

长度1 <= length <= 255

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json