媒体指南
从火山迁移 Seedance
保留火山请求格式,把 Seedance 切换到 TokenLab
已有火山 Seedance 应用可以继续使用原来的 REST 路径、content[] 请求体、响应字段、回调和 PascalCase 素材 Action。只需更换 API 主机,并把 AK/SK 签名换成 TokenLab API 密钥。
需要修改的内容
| 变更项 | 现有火山客户端 | TokenLab |
|---|---|---|
| 基础 URL | 你的火山端点 | https://api.tokenlab.sh/ |
| 鉴权 | AK/SK 请求签名 | Authorization: Bearer <TOKENLAB_API_KEY> |
| 任务传输 | 官方 /api/v3/contents/generations/tasks REST 路径 | 保持不变 |
| 素材/验证 Action | Action 和 Version 查询参数 | 保持不变 |
| 任务请求体 | 火山风格的 content[] | 保持不变 |
| 素材请求体 | GroupId、ProjectName 等 PascalCase 字段 | 保持不变 |
| 异步结果 | 火山引擎任务生命周期 | TokenLab cgt-... 任务 ID,支持轮询和可选回调 |
只带 AK/SK 签名的请求会返回 401 AuthenticationError。所有 TokenLab 请求都必须包含 Authorization: Bearer <TOKENLAB_API_KEY>。
选择接口
| 现有客户端 | TokenLab 接口 |
|---|---|
| 火山 REST 任务客户端 | /api/v3/contents/generations/tasks 及其任务路径 |
| 素材或验证 Action 客户端 | POST /?Action=...&Version=2024-01-01 或 POST /api/v3?Action=...&Version=2024-01-01 |
视频任务请保持原有的 REST 方法、路径和 JSON 请求体。素材和验证请求继续使用 Action 和 Version 查询参数。Action 端点也接受任务类 Action:CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks 和 DeleteContentsGenerationsTasks;新接入请使用 REST 路径。
官方任务路径
| 方法与路径 | 用途 |
|---|---|
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} | 取消仍在排队的任务;已开始的任务返回 409 task_not_cancellable |
REST 客户端可以参考以下对应页面:
请求体规则
content[]支持text、image_url、video_url、audio_url和draft_task项。- 对
image_url,图生视频时省略role或使用first_frame。last_frame需与首帧一起使用;参考图生视频使用reference_image。 - 所选 Seedance 工作流接受对应媒体角色时,可以使用
asset://asset-YYYYMMDDHHMMSS-xxxxx这类公开素材 URI。 - REST 请求体只接受官方字段,包括
model、content、ratio、duration、resolution、generate_audio、watermark、return_last_frame、seed、execution_expires_after和safety_identifier。默认值因模型而异:generate_audio在seedance-2.0系列为false,在seedance-2.5为true;duration在seedance-2.0系列为5,在seedance-2.5为-1。这种 REST 格式的resolution接受480p、720p和1080p(seedance-2.5只有480p和720p),不接受4k;4k只有统一的/v1/videos/generations接口支持。seedance-2.5会拒绝seed、frames和camera_fixed。 callback_url接受公网 HTTP(S) 端点。TokenLab 会在queued、running、succeeded、failed和expired时发送与查询任务相同的请求体;只有succeeded和failed采用官方行为:五秒超时,你的端点没有确认时会重试。
最小 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"
}'保存返回的 cgt-... ID。轮询直到 status 变为 succeeded、failed、cancelled 或 expired;不要把创建响应当作已完成的视频。如果提供了 callback_url,请允许重复收到 succeeded 或 failed 通知,并保留轮询作为恢复手段。
区分 v1 与 v3 类型
不要把 /v1/tasks/{id} 的响应 struct 复用于本接口。统一 v1 API 的状态是 pending、processing、completed、failed;火山兼容 v3 API 的状态是 queued、running、succeeded、failed、cancelled、expired。官方 v3 响应还将 duration 表示为 JSON 字符串,并在非失败任务上省略 error。
为了在创建超时或连接断开后安全恢复,请在 REST 创建请求中添加唯一的 Idempotency-Key。使用同一 key 重试相同请求体会返回原 cgt-... ID;同一 key 配不同请求体返回 409。
素材与真人验证
同一个 Action 入口也支持 10 个素材和素材组操作。请参阅素材 Action(火山兼容)了解其 PascalCase 请求体、筛选、分页、响应信封和 12 小时素材 URL。
真人素材在上传前需要额外两个 Action:
第二个 Action 会返回已验证的 GroupId。将该 ID 用于 CreateAsset;客户端不能直接创建 LivenessFace 分组。
迁移检查清单
- 把 API 主机替换为
https://api.tokenlab.sh。 - 把 AK/SK 签名替换为 TokenLab Bearer API 密钥。
- 保留官方 REST 任务的方法、路径和请求体大小写;仅素材或验证操作保留 Action 和版本。
- 相关的素材和验证请求使用相同的
ProjectName。 - 保存这些接口返回的 TokenLab 任务、素材组和素材 ID。
- 将生产流量切换过来之前,验证一次创建、轮询、列表和错误响应。