TokenLab

媒體指南

將 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 路徑保留
素材/驗證 ActionsAction 和 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/generations API 接受)。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:

  1. 建立視覺驗證工作階段
  2. 取得視覺驗證結果

第二個 Action 會回傳驗證後的 GroupId。請將該 ID 用於 CreateAsset;客戶端無法直接建立 LivenessFace 群組。

遷移檢查清單

  1. 將 API 主機替換為 https://api.tokenlab.sh。
  2. 將 AK/SK 簽章替換為 TokenLab Bearer API 金鑰。
  3. 保留官方 REST 任務方法、路徑和請求主體大小寫;僅在素材或驗證操作中保留 Action 和版本。
  4. 在相關的素材和驗證請求中保持相同的 ProjectName。
  5. 儲存這些端點回傳的 TokenLab 任務、群組和資產 ID。
  6. 在轉移生產流量之前,請先驗證建立、輪詢、列出和錯誤回應。

本頁內容