視頻與素材
建立任務 (Volc 相容)
使用 Volc 相容 API 建立 Seedance 任務。
概覽
現有的 Volc 風格 Seedance 客戶端可以透過更改 API 位址和金鑰來使用 TokenLab。
這些範例使用 Seedance 2.0。此端點也支援 Seedance 2.5,並具有以下模型特定的差異。本頁面中可重複使用的 TokenLab 素材 URI 範例適用於 Seedance 2.0。
另請參閱 Seedance 2.0 影片模型 與 影片生成。
驗證與端點
- 使用
Authorization: Bearer <TOKENLAB_API_KEY>。 - 不接受 Volc 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 個音訊、1 個draft_task)。Seedance 2.5 最多接受 51 個(1 個文字、30 個圖像、10 個影片、10 個音訊、1 個draft_task)。 image_url.url接受公開圖像 URL 或素材 URI,例如asset://asset-YYYYMMDDHHMMSS-xxxxx。role決定該素材是首幀、末幀還是參考圖像。- 請勿在同一個請求中混合使用首/末幀輸入與參考媒體。
- REST 本體僅接受本頁面列出的欄位。任何其他頂層欄位(包括
material_asset_id和material_asset_ids)將回傳400 UnsupportedParameter。請將 TokenLab 素材 URI 放入image_url.url中。
參數說明
model 接受 TokenLab 模型 ID,例如 seedance-2.0 或 seedance-2.5。現有客戶端可以繼續發送他們已用於這些模型的 Volcengine 模型 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 僅對 Seedance 2.5 接受 mp4 或 mov。
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可指向最多 2,048 個字元的公開 HTTP(S) 端點。
回調傳遞 (Callback Delivery)
當存在 callback_url 時,TokenLab 會在任務狀態變更時發送 HTTP POST。回調狀態包括 queued、running、succeeded、failed 和 expired。JSON 本體與取得任務的回應相符。
2xx 回應表示傳遞成功。對於 succeeded 和 failed,若傳遞未能在五秒內成功,將重試最多三次。回調僅包含標準 JSON 內容標頭,沒有 TokenLab 特定的傳遞標頭。不支援重新導向,且私人或保留網路目標將被拒絕。
請儲存任務 ID。如果回調未傳遞,您仍然可以使用取得任務端點來檢索結果。
圖像準備
公開的 HTTP(S) 圖像 URL 和支援的資料 URL 將按原樣使用;它們不會自動儲存為可重複使用的素材。明確的 asset://asset-... 參照會使用現有的 TokenLab 素材。TokenLab 會在生成前檢查所有權和就緒狀態。如果參照的素材仍在準備中,請等待其就緒後再重試;當建立失敗時,請檢查 error.code 和 error.message。
對於現有素材,請使用公開的 asset-YYYYMMDDHHMMSS-xxxxx ID,而不是其他系統回傳的原始資產 ID。TokenLab 會在生成前驗證素材所有權。
建立回應
{
"id": "cgt-20260102030405-a1b2c"
}建立回應僅包含任務 ID。請儲存它,以便隨時檢索狀態和結果。
防止重複任務
在建立請求時發送唯一的 Idempotency-Key(1–255 個字元,無換行符)。如果連線在回應到達前中斷,請使用相同的 API 金鑰、冪等性金鑰 (idempotency key) 和請求本體進行重試:
- 如果原始任務已建立,TokenLab 會回傳相同的
cgt-...ID 並加入Idempotency-Replayed: true。 - 使用相同的金鑰但不同的本體會回傳
409,錯誤代碼為idempotency_conflict,且不會建立第二個任務。 - 超過 255 個字元或包含換行符的金鑰會回傳
400 InvalidParameter。
該金鑰不會改變 JSON 回應的格式。TokenLab 不會從 X-Request-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.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 上的 Actions 使用,包括 CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks 和 DeleteContentsGenerationsTasks。新的整合應使用上述的 REST 路徑。
下一步
使用回傳的 cgt-... ID 搭配 取得任務 (Volc 相容),直到任務達到終止狀態。
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 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
由用戶端產生的金鑰,用於冪等(idempotent)REST 任務建立,長度為 1-255 個字元且不含換行符號。在相同的 TokenLab API 憑證下,若使用相同的金鑰與 JSON 本體重複請求,將傳回原始的 cgt 任務 ID;若使用不同的本體,將傳回 409 並附帶代碼 idempotency_conflict。金鑰過長或包含換行符號將回傳 400。在逾時或中斷後重試時,請保持憑證、金鑰與請求本體不變。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json