创建任务（火山兼容）

概览Copy Anchor Link

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

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

鉴权与入口Copy Anchor Link

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

内容规则Copy Anchor Link

• type: "text" 表示提示词文本。
• type: "image_url" 不传 role 或传 role: "first_frame" 时按首帧处理。
• role: "last_frame" 必须和首帧一起使用。
• role: "reference_image"、reference_video、reference_audio 表示参考素材。
• image_url.url 可以是公网图片 URL，也可以是 asset://asset-YYYYMMDDHHMMSS-xxxxx 形式的 TokenLab 素材 URI；role 决定该素材是首帧、尾帧还是参考图。
• 同一个请求里不要混用首尾帧输入和参考素材。
• 不接受顶层 material_asset_id 和 material_asset_ids。请将 TokenLab 素材 URI 放入 image_url.url。priority 仅 Seedance 2.5 支持。

参数说明Copy Anchor Link

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

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。
• watermark、return_last_frame、seed、execution_expires_after 和 safety_identifier 在符合所选模型规则时可用。
• callback_url 可填写公网 HTTP(S) 地址。

Callback 回调Copy Anchor Link

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

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

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

图片准备Copy Anchor Link

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

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

创建响应Copy Anchor Link

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

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

避免重复创建Copy Anchor Link

创建请求建议携带唯一的 Idempotency-Key。如果连接在响应返回前中断，请使用同一枚 API 密钥、同一个 key 和相同的请求体重试：

• 任务已经创建时，返回相同的 cgt-... ID，并附带 Idempotency-Replayed: true。
• 请求仍在登记中时，返回 409 IdempotencyRequestInProgress；稍后使用同一个 key 和相同请求体重试。
• 同一个 key 配不同请求体时返回 409 IdempotencyConflict，不会再创建第二个任务。

Idempotency-Key 适用于这个 v3 REST 创建接口。X-Request-ID 或相同请求体不会自动防止重复创建。

示例Copy Anchor Link

REST 创建Copy Anchor Link

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": "doubao-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"}
  }
]

查询结果Copy Anchor Link

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

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "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"}