Kling 3.0 API：遷移指南、Motion Control 與程式碼

把 Kling 2.6 的請求裡模型字串換掉，並不代表就能安全升級到 3.0。Kling 3.0 雖然已正式推出，但 V3、Turbo、Omni 與 Motion Control 各自提供不同能力與請求結構。穩妥的做法是先選定路線，再逐一加入音訊、多鏡頭與參考控制等功能。

先選對端點，再開始寫程式

Kling 官方的 VIDEO 3.0 指南將 3.0 定位為 VIDEO 2.6 與 VIDEO O1 的後繼版本：VIDEO 2.6 升級為 VIDEO 3.0，而 VIDEO O1 則升級為 VIDEO 3.0 Omni。開發者 API 針對不同模型提供獨立操作，因此「Kling 3.0 API」更像是一組存取路線，而不是共用同一份請求主體的單一 API。

整合時最常見的錯誤，是把服務商提供的便利 schema 和 Kling 直接 API 的 schema 混為一談：Krea 的託管請求可作為可運作的範例，但不代表相同 URL 或欄位也適用於官方 Kling 開發者文件。

若想先掌握各路線的整體概況，可參考Kling API 整合指南。本文聚焦於 Kling 3.0 的遷移與端點行為。

從 Kling 2.6 升級到 3.0，真正多了什麼

Kling 的第一方模型指南指出，這次升級的重點在於控制能力、連續性與影音導演能力，而不只是提高解析度預設值。下表依據 Kling 為此模型家族列出的能力整理。

實際上，原本以短提示詞為核心的 2.6 整合，在 3.0 可以轉為有明確導演指令的連續段落。Kling 的指南也宣稱，在鏡頭移動期間能更好地保留角色、物件與場景細節；不過，它並未公布獨立的一致性基準測試。因此，這項宣稱應與你的應用實際可驗證的結果分開看待。

建立最精簡可用的非同步 Krea 託管整合

影片生成是非同步作業。應用程式應提交工作、保留任務識別碼，接著輪詢或接收回呼，並保存完成後的輸出結果。不要在模型渲染期間一直維持原始 HTTP 請求連線。

以下範例採用 Krea 公開文件中的 Kling 3.0 端點，因為其請求與工作欄位已在公開的Kling 3.0 API 指南中明確列出。只有在確認預計使用的官方 Kling schema 後，才替換服務商專屬 URL 與欄位名稱。

提交生成工作

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

Krea 文件中的回應包含 job_id，以及例如 scheduled 的初始狀態。服務商範例會使用獨立的工作查詢端點來檢查狀態。開始輪詢前，資料庫應先將 job ID 與你自己的訂單 ID 一併儲存。

設定逾時輪詢並保存輸出

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Krea 的範例分別耗時 51 秒與 2 分 3 秒，因此逾時設定應考量佇列狀況，不要承諾固定的 Kling 生成時間。

進入正式環境後，可透過 webhook 避免重複輪詢。請確認 job ID 對應到由你的系統建立的工作、讓處理程序具備冪等性，而且不要只因收到未簽章的回呼就將其視為身分證明。

逐一加入 3.0 控制項

直接使用 Kling API 與透過託管服務商時，參數名稱可能不同。建議建立小型相容層，不要讓服務商專屬 JSON 擴散到整個應用程式。

官方指南支援原生音訊、元素參考、多鏡頭敘事，以及五種指定的對白語言；但你選用的 API 端點未必會開放此模型家族功能集中的全部項目。

自訂多鏡頭 payload 範例

Krea 文件中的 schema 使用帶有時間的 multi_prompt 段落。對託管整合來說，這是一個實用模式：

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

請驗證頂層 duration 是否等於各段 duration 的總和。Krea 對一項三段、共 12 秒的測試回報了 12.04 秒結果，因此不要預期檔案時長必然精確到毫秒、完全符合數學計算。

Krea 的每個段落上限為 512 個字元，完整導演式序列則限制在 15 秒內。每一段應寫成鏡頭指令：主體、變化與攝影機，而不是冗長的場景散文。若直接使用的 Kling 路線改採官方鏡頭語法，時間軸模型仍可維持一致，只要在 adapter 邊界轉換 payload 即可。

音訊與語言限制

官方指南列出支援中文、英文、日文、韓文與西班牙文對白，也描述了方言、口音、角色專屬對白與混合語言場景。指南表示，未支援的對白輸入會被翻譯成英文，因此多語言應用不應假設每一種來源語言都能完整保留。

音訊也是成本選擇。Krea 公布的費率中，std 無音訊為每秒 $0.1764，含音訊為 $0.2646；pro 無音訊為 $0.2352，含音訊為 $0.3528。列出的 4K 費率則是不論是否含音訊，皆為每秒 $0.441。這些是 Krea 的價格，並非通用的 Kling API 資費。

較合理的迭代流程，是先產出無聲草稿，最後再為選定的 std 或 pro 成品開啟音訊。

上線前要守住的邊界：成本、速度與失敗處理

Kling 的官方消費者指南列出：VIDEO 3.0 在無原生音訊時，720p 為每秒 6 點數、1080p 為每秒 8 點數；含音訊時，720p 為每秒 9 點數、1080p 為每秒 12 點數。Voice Control 另加每秒 2 點數。這些數字用於說明該指南內的相對成本；未查閱即時開發者定價頁面前，不應將其換算成開發者 API 的美元價格。

實際選擇並不只是「哪個模型最便宜？」而是同時牽涉計費與營運：

失敗情況可依類型處理：

1. 對暫時性的服務商錯誤，以設有上限的指數退避重試。
2. 參數無效時，不要重試，應先由 adapter 修正 payload。
3. 保留用戶端冪等鍵或訂單 ID，避免網路逾時造成未察覺的重複工作。
4. 為批次生成設定硬性的美元或點數上限。
5. 在服務商的暫時 URL 到期前，下載結果或複製到耐久儲存空間。
6. 將模型變體、時長、音訊設定、解析度等級與服務商一併記錄；僅記錄「Kling 3.0」不足以進行成本核算。

Kling 2.6 升級至 3.0 的檢查清單

1. 盤點現有的 2.6 呼叫。記錄模型 ID、圖片輸入、起始／結束影格、時長、音訊與回呼行為。
2. 選擇 3.0 家族路線。提示詞主導的電影感生成選 V3、需要更快路線選 Turbo、O1 風格的多模態流程選 Omni、動作參考工作則選 Motion Control。
3. 建立服務商 adapter。將直接 Kling、Krea 與其他託管服務的 schema 放在各自獨立的轉譯層後方。
4. 先遷移最小請求。在加入音訊或多鏡頭控制前，先測試一支 5 秒、無聲、16:9 的生成任務。
5. 每次測試只加一項控制。依序驗證時長、音訊、鏡頭指令與參考資料，才能更容易隔離有問題的欄位。
6. 測試終態。涵蓋成功、失敗、取消、逾時、重複回呼與輸出 URL 過期等情況。
7. 以成本進行影子上線。使用相同時長與輸出等級，讓固定提示詞集分別跑過 2.6 與 3.0，再決定品質或控制力的提升是否值得切換新路線。

當你的應用程式可以在不改動商業邏輯、計費控制或結果處理的情況下回退模型 ID，遷移才算完成。

Kling 3.0 API 常見問題

Kling 3.0 有官方 API 嗎？

有。Kling 官方開發者文件提供 3.0 各模型專屬的 API 頁面，Kling 的第一方指南也將 VIDEO 3.0 說明為 VIDEO 2.6 的後繼版本。由於部分頁面採用用戶端渲染，確切的端點 schema 應從即時的開發者控制台查看。

Motion Control 是 Kling 3.0 的一個參數嗎？

不要直接這樣假設。Motion Control 是 Kling 生態系中擁有獨立模型頁面的專門能力。應使用所選服務商文件中定義的操作與輸入 schema，而非在一般文字生成影片請求中隨意加入未經驗證的 motion_control 欄位。

Kling VIDEO 3.0 最長可以生成多久？

Kling 官方模型指南指出，VIDEO 3.0 支援彈性的 3 至 15 秒輸出。特定託管路線或 Turbo 路線可能有較窄的限制，因此仍應驗證所選端點。

Kling 3.0 支援原生音訊嗎？

支援。官方 VIDEO 3.0 指南提到角色專屬對白、多種語言、方言與口音。不過音訊是否選配、以及如何計費，取決於端點或服務商 schema。

Kling 3.0 Omni 與標準 Kling 3.0 相同嗎？

不同。Kling 將 VIDEO 3.0 定位為 2.6 的後繼版本，VIDEO 3.0 Omni 則是 O1 的後繼版本。服務商頁面可能會以不同模型 ID 提供它們，並帶有不同的參考或語音控制功能。

Kling 網頁版訂閱可支付 API 呼叫費用嗎？

在即時帳戶文件另有說明前，應將消費者訂閱與開發者 API 計費視為不同系統。API 路線通常需要獨立的開發者帳戶、金鑰與計費設定。

實用的遷移界線其實很簡單：保留 2.6 整合的工作生命週期，替換模型專屬 adapter，並針對實際提供服務的路線驗證每一項新增的 3.0 控制功能。這能避免代價最高的一種失敗：整合看似提交成功，卻在不知不覺間使用了錯誤的變體、音訊模式或計費等級。