Kling 3.0 Turbo API:高併發短影片自動化架構
目標型號:
kling-3.0-turbo
推理介面:https://api.toapis.com/v1/videos/generations
相關閱讀:Kling 3.0 Omni 深挖 · Kling V4 Flash API 指南 · kling-3.0-turbo 參考 · kling-3.0-turbo 型號指南
1. 核心摘要與性能速覽 (TL;DR)
- 先看目錄:規劃稿有時會寫成
kling-3-turbo。該字串不是已文件化的公共型號。2026-11-18 檢查官方生成參考和 型號指南頁面(HTTP 200),列出的固定model值是kling-3.0-turbo。請傳送這一精確字串。 - 約定:向
POST /v1/videos/generations非同步提交,再輪詢GET /v1/videos/generations/{id},直到completed或failed。普通任務也可用GET /v1/tasks/{id}查詢。官方示例使用https://toapis.com(中國大陸使用https://toapis.cn)。本系列其他指南使用https://api.toapis.com。請選定一個源站並保持一致。 - 文件化範圍:
duration為 3 到 15 秒的任意整數(預設5)——不只是 5 秒或 10 秒。resolution為720p或1080p(預設720p)。aspect_ratio(16:9、9:16、1:1)僅適用於文生影片請求。 - 圖片輸入僅支援首幀。 若傳送
reference_images,只有第一張公開 URL 會作為first_frame使用。本整合不支援尾幀或結束幀,額外圖片會被忽略。不要傳送 base64。 - 應丟棄的未核實表述:規劃稿裡的每 5 秒
$0.11、"亞 20 秒"延遲、"30+ 併發"、99.95% SLA 或"便宜 60%"等數字,都不是目前 API 文件內容。只引用實時目錄或型號指南上的數字,並將其視為可能變化的展示價。
2. 官方 Turbo 型號與大量任務約束
在 model 欄位中使用公共型號名。不要替換成規劃稿別名、行銷展示名,或相關的 Omni ID。
| 目錄型號 | 在本文中的角色 | 文件化任務 |
|---|---|---|
kling-3.0-turbo | 本文主型號 | 文生影片,以及僅支援首幀輸入的圖生影片 |
kling-v3-omni | 姊妹 Omni 型號;見 Omni 指南 | 官方 image_list / video_list / element_list 引用,包括首尾幀 |
kling-v3 | 相關的非 Omni v3 型號 | 另有獨立生成參考。不要假定 Turbo 欄位同樣適用 |
官方 Turbo 生成頁面比部分行銷文案更窄。型號指南上的通用描述可能提到更多影片工作流;該 ID 的 API 參考只文件化了文生影片和首幀圖生影片。自動化應對準參考文件,而不是宣傳頁。
| 欄位 | 文件化取值 | 說明 |
|---|---|---|
prompt | 必填字串 | 圖生影片時,作為 Turbo 的 prompt 內容項傳送 |
reference_images | 可選字串陣列 | 只有第一張圖會作為 first_frame 使用;後續項會被忽略 |
resolution | 720p(預設)、1080p | 不是 Omni 的 mode=std/pro 標誌 |
duration | 整數 3–15(預設 5) | 只列出 5 秒和 10 秒的規劃稿是不完整的 |
aspect_ratio | 16:9(預設)、9:16、1:1 | 僅適用於文生影片 |
watermark | 布林值,預設 false | 僅開關官方 Kling 水印;不支援自定義水印物件 |
高頻短影片自動化是建立在這一約定之上的編排問題:
- 一條成片,一個任務。 把每個變體作為獨立的非同步任務提交。在開始輪詢之前,先持久化任務 id(以及你自己的請求 id)。
- 給每次等待設上限。 使用截止時間、至少 5–10 秒並帶抖動的間隔,並在
429時遵守Retry-After。狀態參考指出較長影片可能需要數分鐘;在重新查詢同一 id 之前,用戶端逾時不能當成失敗。 - 不要發明併發 SLA。 官方文件沒有為該型號公佈預留的"30+ 併發"配額。請觀察
429響應和 非同步任務限流參考。批次狀態查詢最多接受 100 個任務 ID。 - 讓圖生影片請求保持誠實。 若鏡頭需要結束幀、Omni 列表或動作參考影片,請改用
kling-v3-omni,而不要給reference_images超載含義。

圖 1:將每個短影片變體提交到 POST /v1/videos/generations,用有上限的迴圈輪詢同一任務 id,僅在 status 為 completed 後讀取 result.data[0].url。
3. 生產級實作:cURL 與 Python
本系列的國際示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。請在同一環境中固定一個源站。路徑、型號 ID 和 Bearer 請求頭保持不變。
步驟 1:用 cURL 提交文生影片草稿
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0-turbo",
"prompt": "A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9",
"watermark": false
}'
圖生影片任務應新增 "reference_images": ["https://example.com/first-frame.png"],不要依賴 aspect_ratio,也不要把第二張圖當成結束幀。
步驟 2:Python 輔助函式、輪詢器與小批次迴圈
下面的片段遵循已文件化的任務狀態路徑,以及 queued / in_progress / completed / failed 狀態。上線前請對照你帳戶可見的 API 參考,確認 id、result.data[0].url 和響應結構。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_ID = "kling-3.0-turbo"
DURATION_RANGE = range(3, 16)
def dispatch_turbo(
prompt: str,
*,
model: str = DOCUMENTED_ID,
resolution: str = "720p",
duration: int = 5,
aspect_ratio: str = "16:9",
reference_images: list[str] | None = None,
watermark: bool = False,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-3.0-turbo; kling-3-turbo is not a documented public ID")
if resolution not in {"720p", "1080p"}:
raise ValueError("resolution must be 720p or 1080p")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
payload = {
"model": model,
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"watermark": watermark,
}
if reference_images:
payload["reference_images"] = reference_images[:1]
else:
payload["aspect_ratio"] = aspect_ratio
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
def dispatch_batch(prompts: list[str], **kwargs) -> list[str]:
"""Submit every prompt first, then poll. A failed submit must not hide already-issued ids."""
task_ids = []
for prompt in prompts:
task_ids.append(dispatch_turbo(prompt, **kwargs))
return task_ids
if __name__ == "__main__":
variants = [
"A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"The same shoe on a wet evening street, slower tracking shot, warm storefront light",
]
ids = dispatch_batch(variants, resolution="720p", duration=5)
for task_id in ids:
print("Task:", task_id)
print("Video:", poll_task(task_id))
請把提示詞模板版本與每條任務記錄放在一起,以便區分解析度或時長改動與措辭改動。在 expires_at 之前下載每個檔案;狀態參考寫明保留視窗為 30 天。
4. 錯誤處理與狀態碼對照
下表是排查起點,並不保證與 ToAPIs 的精確錯誤碼一一對應。HTTP 查詢成功後,仍須讀取任務 status。請求錯誤與 status: failed 的原因(例如 content_policy_rejected、insufficient_user_balance 或 generation_timeout)見 錯誤參考。
| HTTP 或任務狀態 | 常見類別 | 建議操作 |
|---|---|---|
400 | 欄位無效、不支援的時長或解析度,或該整合不接受的媒體型別 | 確認型號為 kling-3.0-turbo,duration 為 3–15,resolution 為 720p 或 1080p,且任何圖片都是公開 URL |
401 | 缺少或無效的 API Key | 在 ToAPIs 控制檯輪換金鑰,並確認 Authorization: Bearer 請求頭 |
429 | 速率或併發限制 | 若存在 Retry-After 請遵守;加抖動退避;透過降低提交壓力處理,而不是發明預留配額 |
5xx 或用戶端逾時 | 閘道器或上游暫時異常 | 先查詢已有任務 id,再決定是否重新提交 |
status: queued 或 in_progress | 不是錯誤 | 繼續等待並輪詢;不要為同一提示詞建立第二個任務 |
status: failed | 生成未成功 | 讀取 error.code 與 error.message(若有 error.reason 一併檢視)。不要對未修改的策略拒絕載荷直接重試 |
5. 定價與 FinOps ROI
2026-11-18 獲取的 kling-3.0-turbo 型號指南頁面 給出了如下展示對比價,並在頁面中註明價格可能變化,最終計費以帳戶目前價格、時長、解析度、比例和提交參數為準:
| 規格 | ToAPIs 展示價(2026-11-18) | 同一頁面上的官方展示價 |
|---|---|---|
720p | 每秒 $0.08 | 每秒 $0.1143 |
1080p | 每秒 $0.1 | 每秒 $0.1429 |
倉庫內的型號指南配置列出了相同的 ToAPIs 展示數字,以及 720p 每秒 16 積分、1080p 每秒 20 積分的積分行。請把這些都視為快照,而不是合同。不要沿用規劃稿裡"1000 條成片 380 美元"一類算術。
- 先用
720p打樣。 把時長控制得保守一些(文件預設是 5 秒),為提示詞模板做版本管理,一次只改一個變數。 - 展示價格不等於渠道保證。 預測批次成本前,請用
GET /v1/models?type=video以及帳戶中的實時報價確認 ID 和可用性。 - 在編排層控制支出:持久化每個任務 id,用戶端逾時後先查狀態再決定是否重提,並在
expires_at之前下載結果。官方供應商合同常有承諾期或預付門檻;ToAPIs 計費通常是按量付費——請以帳戶目前條款為準。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:傳送 kling-3.0-turbo,不要傳送 kling-3-turbo;時長為 3–15 秒;圖片輸入僅支援首幀;沒有已文件化的 Turbo 音訊或 Omni 列表約定;輪詢 generations 狀態路徑,持久化每個任務 id,不要發明 SLA。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立金鑰。
- 透過
GET /v1/models?type=video確認你的金鑰能看到kling-3.0-turbo——不要傳送kling-3-turbo。 - 用
resolution: "720p"、duration: 5和aspect_ratio: "16:9"冒煙測試上文 cURL 示例。 - 在有上限的時限內輪詢
GET /v1/videos/generations/{id},並在expires_at之前下載結果。 - 接下來:需要官方 Omni 引用或結束幀時閱讀 Kling 3.0 Omni 深挖,檢視 kling-3.0-turbo 型號指南 瞭解目錄現狀,若需要另一套 Kling 約定則參考 Kling V4 Flash 指南。







