建立影片 - TokenLab

概覽

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

輪詢行為

建立回應會返回規範非同步識別 id，並通常同時回傳 task_id。請優先輪詢 poll_url；如果需要固定狀態入口，請使用 GET /v1/tasks/{id}。如果建立回應返回 poll_url，請直接使用該 URL。若它指向 /v1/tasks/{id}，請將其視為規範的固定狀態查詢入口。為了獲得最可靠的輪詢行為，請嚴格使用建立請求回傳的 poll_url。

模型與媒體行為

音訊輸出是否開啟取決於具體模型。在 TokenLab 中，Veo 3 與 Seedance 請求在省略 output_audio 時預設按開啟音訊處理。模型支援音訊控制時，可用 output_audio 明確切換；相容別名 outputAudio 和 generate_audio 也可使用，但多個欄位同時出現時值必須一致。在生產環境中，建議優先使用可從公網直接存取的 https URL 作為圖片、影片與音訊輸入。相容模型仍支援內嵌 data: URL，但大體積 base64 在重試、觀測與除錯時通常較不友善。

請求主體

model

string

預設值:"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

prompt

string

必填

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

operation

string

要執行的影片操作。支援 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_url

string

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

image

string

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

reference_images

array

用於參考圖生影片的參考圖輸入。可傳數量取決於模型。對於 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_id

string

建立素材或自動圖片準備流程回傳的 TokenLab Seedance 素材 ID。素材變為 ACTIVE 後，可在能夠使用 TokenLab 素材庫的 Seedance 模型中使用。

material_asset_ids

array

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

當所選 Seedance 模型可使用 TokenLab 素材庫時，TokenLab 會在生成前將圖片欄位（image、image_url、image_urls、reference_images、start_image、end_image）準備為可重複使用素材。如果 60 秒內仍未準備完成，API 會回傳 409 seedance_material_preparing 和 auto_material_asset_ids；請在這些素材變為 ACTIVE 後重試。如果所選模型暫不可使用素材庫，一般圖片輸入仍走常規圖片路徑；明確傳入素材 ID 會安全失敗，並回傳可重試的素材可用性錯誤。

reference_image_type

string

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

kling_elements

array

kling-3.0-video 的元素引用定義，僅支援帶圖片條件的請求。可定義 1-3 個元素；每個元素包含 name、可選 description，以及 2-4 個圖片 URL 的 element_input_urls。在 prompt 中用 @name 引用元素。不要將 kling_elements 與 output_audio=true 組合使用；使用元素引用時請省略 output_audio 或設為 false。

video_url

string

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

video_urls

array

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

audio_url

string

提供給 audio-to-video 模型使用的公網音訊 URL。

audio_urls

array

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

task_id

string

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

extend_at

integer

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

extend_times

string

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

duration

integer

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

seconds

integer

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

aspect_ratio

string

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

resolution

string

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

output_audio

boolean

規範的音訊輸出開關。Veo 3 和 Seedance 省略時預設 true。kling-3.0-video 僅在非元素引用請求中接受該欄位，省略時預設無聲。不要將 output_audio=true 與 kling_elements 組合使用。

draft

boolean

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

draft_task_id

string

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

ratio

string

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

generate_audio

boolean

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

execution_expires_after

integer

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

priority

integer

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

safety_identifier

string

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

service_tier

string

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

frames

integer

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

camera_fixed

boolean

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

fps

integer

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

negative_prompt

string

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

seed

integer

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

cfg_scale

number

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

motion_strength

number

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

start_image

string

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

end_image

string

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

size

string

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

watermark

boolean

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

effect_type

string

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

user

string

終端使用者的唯一標識。對 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.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

回應

string

規範非同步任務 ID。

task_id

string

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

poll_url

string

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

billing_transaction_id

string

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

status

string

初始狀態：pending。

created

integer

建立任務時的 Unix 時間戳。

model

string

所使用的模型。

video_url

string

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

video

object

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

videos

array

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

error

string

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

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"
  }'

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "veo3.1",
        "prompt": "A cat walking through a garden, cinematic lighting",
        "operation": "text-to-video",
        "duration": 4,
        "aspect_ratio": "16:9"
    }
)

data = response.json()
task_id = data["task_id"]
print(f"Poll URL: {data['poll_url']}")
print(f"Task ID: {task_id}")

{
  "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,
        "aspect_ratio": "16:9"
    }
)

Kling 3.0 元素引用

需要元素引用時，請在 kling-3.0-video 請求中傳入 kling_elements。請求需要包含圖片條件輸入（image_url、image_urls、start_image 或 end_image），並在提示詞中用 @name 引用對應元素。

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

參考圖生影片

當模型支援專門的參考條件控制時，請使用 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",
        "prompt": "Smooth transition from day to night",
        "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，請在 video_url 中傳入公開 HTTPS .mp4 URL。TokenLab 會把它轉換為 xAI REST 的 video.url 請求體。你可以將 resolution 設為 480p 或 720p；此編輯流程不接受 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.",
        "resolution": "720p"
    }
)

動作控制

當模型同時需要主體圖片與動作參考影片時，請使用 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" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

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

​概覽

​輪詢行為

​模型與媒體行為

​請求主體

​相容說明

​輸入最佳實踐

​Seedance 參數

​Seedance 範例

​回應

​圖生影片

​Kling 3.0 元素引用

​參考圖生影片

​首尾幀控制

​影片轉影片

​動作控制

​模型探索

概覽

輪詢行為

模型與媒體行為

請求主體

相容說明

輸入最佳實踐

Seedance 參數

Seedance 範例

回應

圖生影片

Kling 3.0 元素引用

參考圖生影片

首尾幀控制

影片轉影片

動作控制

模型探索