媒体指南
从火山迁移 Seedance
保留火山请求格式，把 Seedance 切换到 TokenLab
已有火山 Seedance 客户端可以继续使用原来的 REST 路径、content[] 请求体、响应字段、回调和 PascalCase 素材 Action。只需更换 API 地址，并把 AK/SK 签名换成 TokenLab API 密钥。
需要修改的内容
| 需要更换的部分 | 现有火山客户端 | TokenLab |
|---|---|---|
| 基础 URL | Volcengine API | https://api.tokenlab.sh/ |
| 鉴权 | AK/SK | Authorization: Bearer <TOKENLAB_API_KEY> |
| 任务传输 | 官方 /api/v3/contents/generations/tasks REST 路径 | 保持不变 |
| 素材/验证 Action | Action, Version | 保持不变 |
| 任务请求体 | content[] | content[] |
| 素材请求体 | PascalCase | PascalCase |
| 异步结果 | 任务 ID | cgt-... + 状态查询 + 可选 callback |
只带 AK/SK 的请求会返回 401 AuthenticationError。所有 TokenLab 请求都要使用 Authorization: Bearer <TOKENLAB_API_KEY>。
选择接口
视频任务继续使用 /api/v3/contents/generations/tasks；素材和真人验证继续使用带 Action 与 Version 的请求。现有请求体无需改成 /v1/videos/generations 格式。全新的视频功能可以直接使用 TokenLab 的视频生成 API。
需要改什么
- 使用
Authorization: Bearer <TOKENLAB_API_KEY>鉴权。当前版本不接受火山 AK/SK 签名。 - REST 创建使用
POST /api/v3/contents/generations/tasks。任务 Action 别名只作为 TokenLab 旧版兼容入口保留，不属于一比一官方任务契约。 - 创建响应返回
cgt-...任务 ID。通过查询任务 API 查看状态，直到变为succeeded、failed、cancelled或expired。 - 可以传入公网 HTTP(S)
callback_url。状态变化时，回调会发送与查询 API 相同的任务对象。succeeded和failed回调如果五秒内没有成功，最多重试三次。即使使用回调，也应保留状态查询能力。
请求体要点
content[]支持text、image_url、video_url、audio_url和draft_task。image_url不传role或传first_frame时表示首帧；last_frame必须和首帧一起使用；reference_image表示参考图。- 普通图片 URL 按媒体输入处理，不会自动保存成可复用素材。需要复用时，请先创建素材并等待
ACTIVE，再传入asset://<id>。素材准备中时，兼容接口返回错误的code和message；使用已保存的素材 ID 查询状态后再重试。 - REST 请求只接受官方字段，包括
model、content、ratio、duration、resolution、generate_audio、watermark、return_last_frame、seed、execution_expires_after和safety_identifier；generate_audio默认值为false。
参考页面
官方任务路径
| 方法与路径 | 用途 |
|---|---|
POST /api/v3/contents/generations/tasks | 创建视频任务 |
GET /api/v3/contents/generations/tasks/{id} | 查询单个任务 |
GET /api/v3/contents/generations/tasks | 列出任务 |
DELETE /api/v3/contents/generations/tasks/{id} | 取消或删除任务 |
最小 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.5",
"content":[
{"type":"text","text":"A cinematic product reveal"},
{"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
],
"ratio":"16:9",
"duration":5,
"resolution":"720p"
}'素材与真人验证
同一个 Action 入口也支持 10 个素材和素材组操作。请查看火山兼容素材 Action了解 PascalCase 请求体、筛选、分页、响应信封和 12 小时素材 URL。真人素材在上传前还需要调用创建视觉验证会话和获取视觉验证结果。
迁移检查清单
- 把 API 主机替换为
https://api.tokenlab.sh。 - 把 AK/SK 签名替换为 TokenLab Bearer API 密钥。
- 任务请求保留官方 REST 方法、路径和请求体大小写；只有素材与验证操作继续保留 Action 和版本。
- 相关素材和真人验证请求使用相同的
ProjectName。 - 保存 TokenLab 返回的任务、素材组和素材 ID。
- 正式切换前，确认创建、状态查询、列表和错误响应都能正确处理。
不要混用 v1 与 v3 类型
不要把 /v1/tasks/{id} 的响应 struct 直接用于本接口。统一 v1 的状态是 pending、processing、completed、failed；火山兼容 v3 的状态是 queued、running、succeeded、failed、cancelled、expired。官方 v3 响应中的 duration 是 JSON 字符串，非失败任务不返回 error。
为避免创建超时或连接断开后重复生成，REST 创建请求应携带唯一的 Idempotency-Key。使用同一 key 和不变请求体重试会找回原 cgt-... ID；同一 key 配不同请求体返回 409。