建立任務 (Volc 相容)

概覽Copy Anchor Link

現有的 Volc 風格 Seedance 客戶端可以透過更改 API 位址和金鑰來使用 TokenLab。

請參閱 Seedance 2.0 影片模型 與 影片生成。

驗證與端點Copy Anchor Link

• 使用 Authorization: Bearer <TOKENLAB_API_KEY>。
• 不接受 Volc AK/SK 簽章。請求必須包含 TokenLab Bearer 金鑰。
• 使用官方任務路徑：POST /api/v3/contents/generations/tasks。

內容規則Copy Anchor Link

• type: "text" 為提示詞文字。
• type: "image_url" 若無 role，或設定為 role: "first_frame"，將被視為首幀。
• role: "last_frame" 必須與首幀搭配使用。
• role: "reference_image"、reference_video 和 reference_audio 用作參考素材。
• image_url.url 接受公開圖片 URL 或素材 URI，例如 asset://asset-YYYYMMDDHHMMSS-xxxxx。role 決定該素材是首幀、末幀還是參考圖片。
• 請勿在同一個請求中混合使用首/末幀輸入與參考媒體。
• 不接受頂層 material_asset_id 和 material_asset_ids。請將 TokenLab 素材 URI 放入 image_url.url。priority 僅 Seedance 2.5 支援。

參數說明Copy Anchor Link

duration 為整數秒數，-1 表示自動時長。預設值與限制因模型而異：

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。
• 當所選模型支援時，接受 watermark、return_last_frame、seed、execution_expires_after 和 safety_identifier。
• callback_url 可指向公開的 HTTP(S) 端點。

回調傳遞 (Callback Delivery)Copy Anchor Link

當存在 callback_url 時，TokenLab 會在任務狀態變更時發送 HTTP POST 請求。回調狀態包括 queued、running、succeeded、failed 和 expired。JSON 主體與 get-task 回應格式一致。

2xx 回應表示已確認送達。對於 succeeded 和 failed 狀態，若五秒內未成功送達，將重試最多三次。回調僅包含標準 JSON 內容標頭，不包含 TokenLab 特定的傳遞標頭。系統不支援重新導向，且會拒絕私有或保留的網路目標。

請儲存任務 ID。如果回調未送達，您仍可透過 get-task 端點擷取結果。

圖片準備Copy Anchor Link

公開 HTTP(S) 圖片 URL 和支援的 data URL 按輸入使用，不會自動儲存為可重複使用的素材。明確的 asset://asset-... 引用使用既有 TokenLab 素材，生成前會檢查歸屬與就緒狀態。如果引用的素材仍在準備，請等待就緒後重試；建立失敗時查看 error.code 和 error.message。

對於現有素材，請使用公開的 asset-YYYYMMDDHHMMSS-xxxxx ID，而非其他系統返回的原始素材 ID。TokenLab 會在生成前驗證素材所有權。

建立回應Copy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

建立回應僅包含任務 ID。請務必儲存它，以便隨時擷取狀態與結果。

防止重複任務Copy Anchor Link

請在建立請求時發送唯一的 Idempotency-Key。如果連線在回應到達前中斷，請使用相同的 API 金鑰、冪等性金鑰 (idempotency key) 和請求主體進行重試：

• 若原始任務已建立，TokenLab 將返回相同的 cgt-... ID 並加入 Idempotency-Replayed: true。
• 若原始請求仍在登記中，TokenLab 會回傳 409 IdempotencyRequestInProgress；請稍後使用相同金鑰與主體重試。
• 若重複使用金鑰但主體不同，將返回 409 IdempotencyConflict 且不會建立第二個任務。

冪等性適用於官方 v3 REST 建立路徑。它不會改變 JSON 回應格式，且不會根據 X-Request-ID 或未帶金鑰的相同請求主體進行推斷。

範例Copy Anchor Link

REST 建立Copy Anchor Link

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": "doubao-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"}
  }
]

下一步Copy Anchor Link

使用返回的 cgt-... ID 搭配 取得任務 (Volc 相容)，直到任務達到終止狀態。

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "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"}