媒體指南
將 Seedance 從 Volcengine 遷移
保留您的 Volcengine 請求格式並將 Seedance 切換至 TokenLab
如果您的應用程式已經在使用 Volcengine Seedance API,您可以保留其 REST 路徑、content[] 主體、回應欄位、回調 (callbacks) 以及 PascalCase 格式的素材 Actions。只需更改 API 主機並將 AK/SK 簽章替換為 TokenLab API 金鑰即可。
變更內容
| 變更項目 | 現有 Volcengine 客戶端 | TokenLab |
|---|---|---|
| Base URL | 您的 Volcengine 端點 | https://api.tokenlab.sh/ |
| 身份驗證 | AK/SK 請求簽章 | Authorization: Bearer <TOKENLAB_API_KEY> |
| 任務傳輸 | 官方 /api/v3/contents/generations/tasks REST 路徑 | 保留 |
| 素材/驗證 Actions | Action 和 Version 查詢參數 | 保留 |
| 任務主體 | Volcengine 風格的 content[] | 保留 |
| 素材主體 | PascalCase 欄位,例如 GroupId 和 ProjectName | 保留 |
| 非同步結果 | Volcengine 任務生命週期 | TokenLab cgt-... 任務 ID,支援輪詢與選用回調 |
僅使用 AK/SK 簽章的請求將會回傳 401 AuthenticationError。每個 TokenLab 請求都必須包含 Authorization: Bearer <TOKENLAB_API_KEY>。
選擇端點
| 現有客戶端 | TokenLab 端點 |
|---|---|
| Volcengine 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 端點也接受任務 Actions 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進行圖生影片 (image-to-video)。將last_frame與第一幀一起使用,或使用reference_image進行參考圖生影片 (reference-to-video)。 - 當所選的 Seedance 工作流程接受該媒體角色時,可以使用公開的素材 URI,例如
asset://asset-YYYYMMDDHHMMSS-xxxxx。 - REST 主體僅接受官方欄位,包括
model、content、ratio、duration、resolution、generate_audio、watermark、return_last_frame、seed、execution_expires_after和safety_identifier。預設值取決於模型:seedance-2.0模型的generate_audio為false,seedance-2.5為true;seedance-2.0模型的duration為5,seedance-2.5為-1。此 REST 格式接受resolution值480p、720p和1080p(seedance-2.5僅支援480p和720p),但不接受4k(僅統一的/v1/videos/generationsAPI 接受)。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} 的回應結構重複用於此端點。統一的 v1 API 回報 pending、processing、completed 和 failed;Volc 相容的 v3 API 回報 queued、running、succeeded、failed、cancelled 和 expired。官方 v3 回應也將 duration 表示為 JSON 字串,並在非失敗任務中省略 error。
為了在建立逾時或連線中斷後安全恢復,請在 REST 建立請求中加入唯一的 Idempotency-Key。使用相同的金鑰重試相同的主體將回傳原始的 cgt-... ID;若使用相同的金鑰但主體不同,則會回傳 409。
素材與真人驗證
相同的 Action 端點也支援 10 種素材與素材群組操作。請參閱 素材 Actions (Volc 相容) 以了解其確切的 PascalCase 主體、篩選器、分頁、回應封裝以及 12 小時有效的素材 URL。
真人驗證素材在上傳前需增加兩個 Actions:
第二個 Action 會回傳驗證後的 GroupId。請將該 ID 用於 CreateAsset;客戶端無法直接建立 LivenessFace 群組。
遷移檢查清單
- 將 API 主機替換為
https://api.tokenlab.sh。 - 將 AK/SK 簽章替換為 TokenLab Bearer API 金鑰。
- 保留官方 REST 任務方法、路徑和請求主體大小寫;僅在素材或驗證操作中保留 Action 和版本。
- 在相關的素材和驗證請求中保持相同的
ProjectName。 - 儲存這些端點回傳的 TokenLab 任務、群組和資產 ID。
- 在轉移生產流量之前,請先驗證建立、輪詢、列出和錯誤回應。