TokenLab

媒體指南

影片生成

從文字、圖片、音訊或現有片段建立影片

影片生成是非同步的。POST /v1/videos/generations 會回傳一個任務 ID 以及通常會包含一個 poll_url。請使用該 ID 輪詢 GET /v1/tasks/{id},直到完成影片準備就緒。

請在您所選模型接受的圖片欄位中,傳送公開的 HTTP(S) URL 或支援的資料 URL。這些輸入遵循一般的媒體路徑,且不會自動建立可重複使用的素材 ID。

當明確的素材仍在準備中時,POST /v1/videos/generations 會回傳 409 seedance_material_preparing 以及 inactive_asset_ids。請輪詢這些資產直到狀態變為 ACTIVE,然後使用相同的素材 ID 重試。如果資產狀態為 FAILED,請檢查 error_message 並在重試前進行修正或重新匯入。

選擇 API

若要進行新的影片整合,請使用 /v1/videos/generations。現有的 Seedance 2.0 客戶若已在傳送 Volcengine content[] 或 Action 請求,可透過 /api/v3 維持該格式。這兩個 API 皆使用 TokenLab Bearer 金鑰,但其欄位與狀態值有所不同。

選擇要建立的內容

請明確設定 operation,以便 API 能針對該工作驗證正確的欄位。

操作 (Operation)必要或典型的輸入使用案例
text-to-videoprompt僅從文字生成
image-to-videoimage_url 或相容的 image將起始圖片製作成動畫
reference-to-videoreference_images 以及支援模型上的選用 video_urls / audio_urls保留識別、風格或素材參考
start-end-to-videostart_image, end_image控制第一幀與最後一幀
video-to-videovideo_url 或模型特定的 task_id轉換或放大現有片段
motion-controlimage_url 加上 video_url將動作參考套用到主體
audio-to-videoaudio_url音訊驅動的影片流程
video-extensiontask_id, extend_at 或模型特定的擴充欄位接續已生成的影片

選擇模型

curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
  -H "Authorization: Bearer sk-your-api-key"

請使用 TokenLab 回傳的模型 ID,然後透過 operation 與對應的媒體輸入選擇生成類型。請勿將操作名稱作為模型 ID 使用。

在依賴 reference_images、kling_elements、output_audio、duration、resolution 或 aspect_ratio 等特殊欄位之前,請先閱讀所選模型的詳細資訊。

建立影片

curl https://api.tokenlab.sh/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "operation": "text-to-video",
    "prompt": "A calm cinematic shot of a cat walking through a sunlit garden",
    "resolution": "720p",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

對於可從網際網路擷取的媒體,請使用 https URL。暫存 URL 必須在 TokenLab 建立任務前保持有效。

模型特定欄位

音訊行為取決於所選的模型與操作。即使未顯示音訊選擇器,影片仍可能包含聲音。省略選擇器與發送 false 是不同的。

  • veo3.1、veo3.1-fast 和 veo3.1-lite 一律會生成音訊。請省略 output_audio 或發送 true;發送 false 將會被拒絕。
  • wan-2.6 和 wan-2.7 一律包含音訊。請省略 output_audio 或發送 true。wan-3.0 和 wan-3.0-prime 同樣一律包含音訊,且不接受任何音訊選擇器。
  • hailuo-h3 會生成原生音訊且沒有靜音開關。請勿發送模型詳細資訊中未列出的音訊選擇器。
  • viduq3-pro 和 viduq3-turbo 預設會生成音訊;若要輸出靜音,請發送 output_audio: false(或 audio: false)。Seedance 和 PixVerse 模型接受 output_audio;請明確發送該參數,而非依賴預設值。僅在列出該參數的操作中使用它。
  • audio_url / audio_urls 用於提供輸入或參考音訊。它們並非音訊輸出開關。影片編輯、動作遷移和風格遷移可能會保留輸入音軌;保留來源音訊並不代表將其靜音。

請檢查模型詳細資訊以獲取允許的值以及與音訊相關的價格。若模型列出了這些別名,則 outputAudio、generate_audio 和布林值 audio 在組合使用時必須與 output_audio 一致。請勿假設同一模型系列中的每個版本或操作都共享相同的音訊控制項。

  • 對於 Seedance 2.0 系列,在使用 4K 輸出、Fast/Mini 解析度上限或多模態參考輸入之前,請先閱讀 Seedance 2.0 影片模型指南。
  • 對於 grok-imagine-video 的影片轉影片 (video-to-video) 功能,請傳送 prompt 以及公開的 HTTPS .mp4 video_url。來自先前任務的 TokenLab .mp4 結果 URL 亦可使用。此操作不使用 duration、resolution 或 aspect_ratio 選擇器。

PixVerse 與 HappyHorse

模型操作輸入解析度時長音訊選擇器
pixverse-c1, pixverse-v6text-to-video, image-to-video, start-end-to-video, reference-to-videoprompt; image_url; start_image + end_image; reference_images360p, 540p, 720p, 1080p1 到 15 秒之間的任意整數output_audio, 預設為 false
pixverse-v5.6text-to-video, image-to-video, start-end-to-video, reference-to-video與 C1 和 V6 相同的欄位360p, 540p, 720p, 1080p5、8 或 10 秒;1080p 支援 5 或 8 秒output_audio, 預設為 false
happyhorse-1.0text-to-video, image-to-video, reference-to-video, video-to-videoprompt; image_url; reference_images; video_url + reference_images720p, 1080p生成操作為 3 到 15 秒;video-to-video 輸出上限為 15 秒請勿傳送 output_audio

在 TokenLab 上,上述 PixVerse 模型不接受 operation=video-extension。

curl https://api.tokenlab.sh/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pixverse-v6",
    "operation": "image-to-video",
    "prompt": "A slow camera move through a neon-lit street",
    "image_url": "https://example.com/start.jpg",
    "resolution": "1080p",
    "duration": 5,
    "output_audio": true
  }'

取得完成的影片

使用建立回應中的 id 或 task_id 呼叫 GET /v1/tasks/{id},直到任務狀態為 completed 或 failed。

已完成的影片任務可能會根據模型與輸出數量回傳 video_url、video 或 videos。請將 billing_transaction_id 視為帳務識別碼,而非任務識別碼。

影片結果 URL 是以檔案類型(如 .mp4)結尾的 TokenLab 媒體結果 URL,有效期為 30 天。media_retention.items 會回報每個項目的儲存狀態與 expires_at;當儲存狀態無法及時得知時,回應可能會省略 media_retention,但該 URL 仍然有效。失敗與進行中的任務會回傳空的影片 URL 欄位。非同步任務快照具有獨立的生命週期。請參閱 資料保留。

常見陷阱

  • 請勿在新的程式碼中使用如 /v1/videos/generations/{id} 等特定模態的狀態路徑;請輪詢 GET /v1/tasks/{id}。
  • 除非模型詳細資訊允許,否則請勿將第一幀欄位與專用的參考圖片流程混合使用。
  • 請勿假設 duration 是指輸入參考影片的長度;它通常用於控制生成輸出的長度。
  • 請在 POST /v1/videos/generations 中傳送 Idempotency-Key。若發生逾時,請使用相同的金鑰傳送相同的請求以取得原始任務。若沒有金鑰,請在重試前檢查任務是否已經建立。

API 參考

主題參考
建立影片建立影片
取得影片狀態取得影片狀態
取得任務狀態取得任務狀態
取消任務取消任務
帳務與定價帳務與定價

Hailuo H3-Max 可從文字、第一幀或第一與最後一幀生成 5–15 秒的 480p 或 768p 影片。其以速度為導向的工作流程,適合將拍攝構想快速轉化為短片。

{
  "model": "hailuo-h3-max",
  "operation": "text-to-video",
  "prompt": "A slow camera move through a quiet garden",
  "resolution": "768p",
  "duration": 5,
  "aspect_ratio": "16:9"
}

本頁內容