TokenLab
取得 API Key
文件API 參考整合

視頻與素材

建立影片

建立一個影片生成任務

POST
/v1/videos/generations

概覽

影片生成是非同步的。你提交請求後，會收到一個任務 ID 與 poll_url，之後再透過輪詢取得結果。

輪詢行為

建立回應會返回規範非同步識別 id，並通常同時回傳 task_id。請優先輪詢 poll_url；如果需要固定狀態入口，請使用 GET /v1/tasks/{id}。

如果建立回應返回 poll_url，請直接使用該 URL。若它指向 /v1/tasks/{id}，請將其視為規範的固定狀態查詢入口。

為了獲得最可靠的輪詢行為，請嚴格使用建立請求回傳的 poll_url。

模型與媒體行為

音訊行為取決於所選模型和操作。沒有音訊開關，不代表影片必須無聲；省略參數也不等於傳送 false。

  • veo3.1 和 veo3.1-fast 依 Gemini API 契約始終產生音訊。wan-2.6 和 wan-2.7 的影片生成也不支援關閉聲音。省略 output_audio；模型詳情允許時亦可設為 true。
  • hailuo-h3 和 Grok 影片模型原生產生音訊。請勿加入所選模型詳情未列出的音訊開關。
  • Seedance 1.5/2.x 與 viduq3-pro / viduq3-turbo 預設開啟音訊，並支援無聲輸出；PixVerse C1/V5.6/V6 預設關閉音訊。僅在目前操作列出該欄位時使用 output_audio；Vidu 亦接受其契約宣告的布林欄位 audio。
  • audio_url / audio_urls 用於輸入或參考音訊，不是輸出聲音開關。影片編輯、動作遷移和風格轉換可能保留輸入音軌；保留原音不等於靜音。

允許值及音訊相關價格以模型詳情為準。受支援的相容欄位 outputAudio、generate_audio 和布林 audio 與 output_audio 同時出現時，值必須一致。請勿假定同系列各版本、各操作的聲音控制相同。

在生產環境中，建議優先使用可從公網直接存取的 https URL 作為圖片、影片與音訊輸入。相容模型仍支援內嵌 data: URL，但大體積 base64 在重試、觀測與除錯時通常較不友善。

請求主體

modelstring預設值: veo3.1

影片模型 ID。請使用 veo3.1、wan-2.7、happyhorse-1.0、viduq3、pixverse-v6、kling-3.0-video 等模型 ID；文生影片、圖生影片、參考圖生影片等能力用 operation 選擇。目前公開影片能力請參考影片生成指南和 Models API。

PixVerse

  • 模型: pixverse-c1, pixverse-v6, pixverse-v5.6
  • 操作: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • 音訊選擇器: output_audio, 預設為 false

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

HappyHorse

  • 模型: happyhorse-1.0
  • 操作: text-to-video, image-to-video, reference-to-video, video-to-video
  • 音訊選擇器: 請勿傳送 output_audio
promptstring

要生成影片的文字描述。大多數公開影片模型都需要這個欄位。

operationstring

要執行的影片操作。支援 text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension、audio-to-video 與 motion-control。TokenLab 可以根據輸入自動推斷操作，但在生產環境中仍建議明確傳入 operation。

image_urlstring

用於圖生影片的起始圖片 URL。為了獲得最廣泛的跨模型相容性，建議優先使用 image_url。

imagestring

以內嵌 data URL 形式提供的圖片（例如 data:image/jpeg;base64,...）。相容模型支援這種方式，但 image_url 的相容性更廣。

reference_imagesarray

用於參考圖生影片的參考圖輸入。可傳數量取決於模型。對於 seedance-2.0 與 seedance-2.0-fast，TokenLab 目前支援最多 9 張參考圖，外加最多 3 段參考影片與 3 段參考音訊。模型選型、4K 邊界和 Mini 說明請參考 Seedance 2.0 影片模型指南。建議優先使用公開 https URL；相容模型也支援內嵌 data: URL。 對於 grok-imagine-video，reference-to-video 最多接受 7 個圖片參考，且 duration 最高為 10 秒。grok-imagine-video-1.5-preview 僅支援圖生影片，不接受參考圖片。

material_asset_idstring

建立素材回傳的 TokenLab Seedance 素材 ID。素材變為 ACTIVE 後，可在能夠使用 TokenLab 素材庫的 Seedance 模型中使用。

material_asset_idsarray

多個 TokenLab Seedance 素材 ID。它們與 reference_images 共用 Seedance 圖片參考數量限制；所選模型必須能夠使用 TokenLab 素材庫。

一般圖片 URL 作為圖片輸入，不會自動建立可重複使用素材。需要重複使用時，先透過素材 API 建立，再使用 TokenLab 素材 ID 或 asset://asset-YYYYMMDDHHMMSS-xxxxx URI。明確指定素材後若收到 409 seedance_material_preparing，請查詢回應中的 inactive_asset_ids，待素材變為 ACTIVE 後重試。

reference_image_typestring

可選的參考圖片角色欄位，用於區分支援 asset 與 style 兩種參考圖類型的模型。

kling_elementsarray

僅當所選模型目前的公開詳情列出 kling_elements 時使用。請求需包含圖片輸入與 1–3 個元素；每個元素包含 name、選填 description 和 2–4 個 element_input_urls，並在 prompt 中以 @name 引用。不能與 output_audio=true 組合。

video_urlstring

來源影片的公開 URL。基於影片 URL 的 video-to-video 流程與 motion-control 需要此欄位；部分衍生流程改用 task_id。

video_urlsarray

用於支援多模態參考條件控制的額外參考影片輸入。可傳數量取決於模型。對於 seedance-2.0 與 seedance-2.0-fast，TokenLab 目前支援最多 3 段參考影片。

audio_urlstring

所選模型支援的音訊驅動或參考音訊操作所用的公開音訊 URL。

audio_urlsarray

用於支援多模態參考條件控制的額外參考音訊輸入。可傳數量取決於模型。對於 seedance-2.0 與 seedance-2.0-fast，TokenLab 目前支援最多 3 段參考音訊。

task_idstring

某些續寫、延展或衍生流程使用的任務標識符。

extend_atinteger

某些 video-extension 流程使用的模型側延展起點參數。

extend_timesstring

某些 video-extension 流程使用的模型側延展次數或倍率參數。

durationinteger

生成輸出影片的時長（秒）。Seedance 1.5/2.0 模型省略時預設 5 秒；傳 -1 表示讓模型在支援範圍內自動選擇時長，任務完成前會按保守方式預估費用。

secondsinteger

duration 的相容別名。若同時傳 seconds 和 duration，兩者必須完全一致。對 Seedance，seconds=-1 與 duration=-1 一樣表示自動時長。

aspect_ratiostring

規範寬高比，例如 adaptive、16:9、9:16、1:1、4:3、3:4 或 21:9。Seedance 省略時預設 adaptive。

resolutionstring

模型相關的輸出解析度。Seedance 省略時預設 720p；seedance-2.0 支援 480p、720p、1080p 和 4k，seedance-2.0-fast / seedance-2.0-mini 僅支援 480p 和 720p。

output_audioboolean

僅用於宣告此欄位的操作。省略時遵循模型預設行為；只有允許時，false 才表示無聲輸出。請參閱上方音訊說明及模型詳情。

draftboolean

Seedance 1.5 Pro 草稿工作流開關。僅在支援草稿任務的 Seedance 模型上使用 draft=true；不要和 draft_task_id 同時傳。

draft_task_idstring

Seedance 1.5 Pro 草稿晉升任務 ID。傳入上一次草稿任務 ID 後建立正式影片；這不是通用影片欄位。

ratiostring

aspect_ratio 的相容別名。若同時傳 ratio 和 aspect_ratio，兩者必須完全一致。

generate_audioboolean

output_audio 的相容別名。generate_audio、output_audio、outputAudio 同時出現時，所有值必須一致。

execution_expires_afterinteger

相容影片模型的執行過期時間（秒）。Seedance 省略時預設 172800 秒。

priorityinteger

相容影片模型的任務優先級，範圍 0 到 9。不要把 priority 與 service_tier=flex 組合使用。

safety_identifierstring

相容影片模型的終端使用者安全標識。Seedance 未傳該欄位時，TokenLab 會使用 user 的值。

service_tierstring

default 對 Seedance 2.0 會按相容 no-op 處理。只有所選模型明確支援時才可使用 flex。

framesinteger

相容影片模型的可選幀數。Seedance 2.0 模型和 Seedance 1.5 Pro 不支援該欄位。

camera_fixedboolean

相容影片模型的固定相機開關。Seedance 2.0 模型不支援該欄位。

fpsinteger

每秒影格數（1-120），僅在模型公開支援 FPS 控制時生效。

negative_promptstring

希望在影片生成過程中避免出現的內容。

seedinteger

用於可重現生成的隨機種子。Seedance 省略時使用 -1 表示隨機種子。

cfg_scalenumber

提示詞遵循強度（0-20），僅在公開模型支援此控制項時生效。

motion_strengthnumber

動作強度（0-1），僅在公開模型支援這個欄位時生效。

start_imagestring

start-end-to-video 中使用的起始幀圖片 URL 或相容圖片輸入。

end_imagestring

start-end-to-video 中使用的結束幀圖片 URL 或相容圖片輸入。

sizestring

相容影片模型使用的模型相關尺寸檔位參數。

watermarkboolean

某些模型暴露的浮水印開關。Seedance 省略時預設 false。

effect_typestring

某些特效或編輯流程所使用的模型側效果選擇器。

userstring

終端使用者的唯一標識。對 Seedance，如果未傳 safety_identifier，TokenLab 會使用該值。

相容說明

  • 規範公開欄位繼續使用 snake_case：aspect_ratio、output_audio、reference_images 和 reference_image_type。
  • 為了相容既有呼叫，TokenLab 也接受 ratio、generate_audio、outputAudio、seconds、referenceImages 和 referenceImageType。
  • 如果規範欄位和別名欄位同時出現，值必須一致；衝突會在建立任務前被拒絕。
  • 如果省略 operation，TokenLab 會根據輸入自動推斷操作；生產環境仍建議明確傳入。

輸入最佳實踐

  • 對於 image_url、reference_images、video_url 與 audio_url，建議優先使用公網可存取的 https URL。
  • 盡量避免在同一個請求中混用內嵌 base64 與遠端 URL；統一採用同一種表示方式更容易排錯與重試。
  • 請確保遠端媒體 URL 的有效期足以覆蓋重試窗口與非同步任務建立流程。

Seedance 參數

對於 Seedance 1.5/2.0 模型，統一介面以 TokenLab 欄位為主，同時接受官方常見別名 ratio 和 generate_audio。省略 Seedance 參數時會使用這些預設值：duration=5、resolution=720p、aspect_ratio=adaptive、output_audio=true、watermark=false、return_last_frame=false、execution_expires_after=172800、priority=0、seed=-1。

duration=-1 或 seconds=-1 表示讓 Seedance 在模型支援範圍內自動選擇輸出時長。TokenLab 會在任務完成前按保守方式預估費用，並在可取得完成任務 usage 時按實際結果結算。service_tier=default 對 Seedance 2.0 作為相容 no-op 接受；service_tier=flex、frames、camera_fixed 會在所選模型不支援時被拒絕。

Seedance 範例

cURL
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

回應

結果、錯誤、時間戳記與模型欄位僅在任務提供時回傳。

idstring

規範非同步任務 ID。

task_idstring

用於輪詢的唯一任務識別碼。

poll_urlstring

此任務建議使用的輪詢 URL。查詢狀態時請使用這個精確路徑。

billing_transaction_idstring

當結算已完成時返回 TokenLab 帳單交易 ID。它對應 dashboard / 對帳使用的交易識別，與非同步 id / task_id 不同。

statusstring

任務狀態：pending、processing、completed、failed。

createdinteger

建立任務時的 Unix 時間戳。

modelstring

所使用的模型。

video_urlstring

結果已就緒時可直接使用的影片 URL。

videoobject

可用時返回單一影片物件，包含 url、duration、width 與 height。

videosarray

當任務生成多個輸出時，可能出現影片陣列。

errorstring | object

任務失敗時返回的錯誤訊息或結構化錯誤物件。

請求

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

回應

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

圖生影片

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "resolution": "768p"
    }
)

Kling 3.0 元素引用

僅當所選模型目前的公開詳情列出 kling_elements 時使用。請求需包含圖片輸入與 1–3 個元素；每個元素包含 name、選填 description 和 2–4 個 element_input_urls，並在 prompt 中以 @name 引用。不能與 output_audio=true 組合。

參考圖生影片

當模型支援專門的參考條件控制時，請使用 operation=reference-to-video。在 TokenLab 請求中，圖片參考素材使用 reference_images，多模態參考影片與參考音訊則分別使用 video_urls 與 audio_urls。對於 seedance-2.0 與 seedance-2.0-fast，TokenLab 目前支援最多 9 張參考圖，外加最多 3 段參考影片與 3 段參考音訊。模型選型、4K 邊界和 Mini 說明請參考 Seedance 2.0 影片模型指南。duration 只控制生成輸出時長，不單獨限制參考影片輸入時長。 對於 grok-imagine-video，reference-to-video 最多接受 7 個圖片參考（reference_images 或 image_urls），且 duration 最高為 10 秒。不要把參考圖片與 image_url / image 首幀輸入混用。grok-imagine-video-1.5-preview 僅支援圖生影片。

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity and palette while adding subtle motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

首尾幀控制

使用 start_image 與 end_image 控制首幀與尾幀：

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)

影片轉影片

grok-imagine-video 的 video-to-video 使用公網 HTTPS .mp4 的 video_url 與編輯提示詞 prompt。此操作請省略 resolution、duration 和 aspect_ratio。

當模型接受現有影片作為主要輸入時，請使用 operation=video-to-video。

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion."
    }
)

動作控制

當模型同時需要主體圖片與動作參考影片時，請使用 operation=motion-control。TokenLab 會把公開的 image_url + video_url 請求形態轉換為相容的動作控制輸入。

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

模型探索

公開影片模型庫存與支援操作會持續變化。接入某個模型特定流程前，請以 Models API 確認目前支援情況：

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

依賴模型特定操作或欄位前，請讀取單模型詳情回應。audio-to-video、video-extension 等操作屬於模型特定能力；請在那裡確認即時可用性，不要依賴本頁的靜態範例。

授權

BearerAuth
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified，並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

獲取音樂狀態

上一頁

建立任務 (Volc 相容)

下一頁