视频与素材
创建任务(火山兼容)
通过火山兼容格式创建 Seedance 任务。
概览
已有火山风格 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_task1);Seedance 2.5 最多 51 个(文本 1、图片 30、视频 10、音频 10、draft_task1)。 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.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (默认: 5) | 4–30 / -1 (默认: -1) |
resolution | 480p, 720p, 1080p (默认: 720p) | 480p, 720p (默认: 720p) |
generate_audio | boolean (默认: false) | boolean (默认: true) |
priority | 不支持 | integer: 0–9 |
seed | integer: -1–4294967295 (默认: -1) | 不支持 |
execution_expires_after | 3600–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 API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
客户端生成的用于幂等 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