Kling API 串接指南：官方平台與聚合服務怎麼選（2026）

要串接 Kling 生成影片，並不存在一支放諸四海皆準的 API。Kling 是快手推出的影片生成模型，除了官方 Open Platform，也可透過 WaveSpeedAI、KIE 與 fal 等聚合服務使用；各家使用的憑證、模型 ID、請求格式與計費方式都不一樣。不過整體流程很一致：送出任務、保存任務 ID、等待進入終態，再取得輸出結果；重點是不要在狀態不明時無限制重試。

先選接入管道，再挑 SDK

Kling 有官方 Open Platform，但搜尋「Kling API」時，也很容易看到第三方閘道服務。別只看模型名稱選方案，應依供應商存取權限、整合速度與帳務控管需求決定接入管道。

若要比較不同解析度的價格，請參考既有的 Kling 3 API 價格指南；本文則將價格、音訊倍率、並發數與失敗任務計費，一律視為各供應商各自設定的項目。

走官方 Kling Open Platform 的流程

若採購流程要求直接與快手合作，或需要第一方模型供應，便應使用官方 Open Platform。目前官方文件將憑證設定、任務建立、回呼、並發規則與錯誤碼分開說明，因此應依官方路徑實作，不要直接套用聚合服務的 payload：

1. 依驗證指南建立或取得官方憑證，並將 token 留在伺服器端。
2. 根據官方參考文件中指定的模型 endpoint 與請求欄位，提交非同步影片生成任務。
3. 若需要狀態主動推送，請加入 callback_url。官方文件列出的 callback 狀態包含 submitted、processing、succeed 與 failed；失敗時請保存 task_status_msg。
4. 在本地端依帳號目前分配到的並發額度限制任務數。官方並發指南指出，超載時會回傳 HTTP 429 與業務碼 1303，不能假設 Kling 一定會替你排隊。
5. 透過官方錯誤碼參考文件，區分憑證錯誤、參數無效、資源耗盡、政策限制，以及可重試的伺服器端失敗。

官方驗證頁面在可存取版本的文件中採用 client-rendered 方式呈現，因此本文不會轉載未經確認的 token 產生程式碼。請直接從該頁複製當前憑證格式，不要假設 WaveSpeed、KIE 或 fal 的 header 可以直接沿用。

即使不猜測其精確 payload，仍可將官方生命週期標準化如下：

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

這只是生命週期示意，並非可直接複製貼上的 endpoint 範例。確切的 token、路徑、請求欄位與回應封裝，仍應以連結的官方參考文件為準。

什麼情況更適合用聚合服務

若是原型開發、需要隨用隨付、想用一個帳號接多種模型，或偏好供應商 SDK，聚合服務通常整合更快。不過 API key、schema、佇列、輸出 URL，甚至檔案保留期限，都由它們決定；重試前務必先辨識是哪一層出了問題。

可安全統一的 Kling API 抽象層

正式環境的 client 應以單一內部函式包裝供應商差異。不論走哪一條管道，你的應用程式都需要完成以下工作：

1. 在花費額度前，先驗證 prompt 與媒體 URL。
2. 使用供應商專屬的模型 ID 提交影片生成任務。
3. 立刻保存回傳的 task ID 或 prediction ID。
4. 接收 callback，或輪詢結果 endpoint，直到任務進入終態。
5. 保存輸出 URL、供應商、模型、參數與成本中繼資料。
6. 供應商回報失敗、取消、逾時或刪除後，停止重試。

抽象層應回傳你自己的標準化物件，例如：

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

跨平台較容易對應的參數

這些概念能對應，但欄位名稱不會相同。generate_audio、sound 與 generate_audio: true 在不同服務中可能描述相關功能。請將每一家供應商的 schema 視為獨立 adapter。

不能直接沿用的參數與格式

第一個常見陷阱就是模型 ID。kling-3.0、kling-3.0/video、fal-ai/kling-video/v3/standard/text-to-video 與 kwaivgi/kling-v3.0-std/text-to-video 指向的是不同 API 路徑，不是可互換的值。

驗證 header、callback 命名、結果 URL、任務狀態值與檔案上傳規則也是如此。若 client 硬編碼某家供應商的狀態字串，例如 completed，就可能誤判另一家回傳的 succeeded 或 failed。

三種實際請求格式

以下是供應商專屬的範例，也正說明了為何不存在單一通用的 Kling endpoint。

WaveSpeedAI：取得 prediction ID 後輪詢結果

WaveSpeedAI 文件列出的 Kling 3.0 Standard 文字轉影片 endpoint 如下：

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

請求使用 Bearer token。Endpoint 會回傳 prediction ID，之後從以下位置讀取結果：

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

最精簡的 cURL 流程如下：

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

WaveSpeedAI 的模型文件列出支援 3–15 秒、16:9、9:16 與 1:1 比例，cfg_scale 預設值為 0.5。其 Standard 價格表顯示，5 秒無聲影片為 $0.42，啟用聲音則為 $0.63；這些數字只是該供應商當前快照，並非通用 Kling 價格。

正式環境應以 backoff 輪詢結果 endpoint，而非在緊密迴圈中持續發送請求。此 endpoint 文件列出的終態包括 completed、failed、cancelled、timeout 與 deleted，遇到這些狀態就應停止。

KIE：createTask 搭配 callback 或任務查詢

KIE 使用共用的任務建立 endpoint：

POST https://api.kie.ai/api/v1/jobs/createTask

Kling 3.0 的模型識別字串為 kling-3.0/video，驗證採用 Bearer token。單鏡頭的精簡 payload 如下：

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

KIE 文件列出支援 3–15 秒影片、16:9、9:16 與 1:1 輸出比例，多鏡頭模式最多可使用五個鏡頭。每個多鏡頭項目可指定 1–12 秒。圖片元素可使用 2–4 個 JPG 或 PNG URL，文件標示每張圖片上限為 10 MB；影片元素則可使用一個 MP4 或 MOV URL，上限為 50 MB。

Callback 雖為選用，但 KIE 建議正式環境啟用。你的 webhook 應在可用時驗證簽章、快速回應確認，並將任務結果送入佇列處理。同時保留任務查詢輪詢機制，以便補救遺漏的 callback。

KIE 針對常見失敗情況定義了不同回應碼，包括驗證無效的 401、額度不足的 402、驗證錯誤的 422，以及速率限制的 429。請將 code 與 message 一起記錄；只看到籠統的「Kling failed」，不足以判斷是否適合重試。

fal：模型 endpoint 搭配佇列 client

fal 透過模型專屬 endpoint ID 提供 Kling 3.0。Standard 文字轉影片使用的文件 ID 為：

fal-ai/kling-video/v3/standard/text-to-video

原始 API 使用 Authorization: Key $FAL_KEY header。Python 與 JavaScript 範例皆採用 fal 具備佇列感知能力的 client，通常比自行撰寫輪詢迴圈簡單。

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

fal 文件列出支援 3–15 秒、三種文字轉影片長寬比，以及 0–1 範圍的 cfg_scale，預設值為 0.5。Standard schema 指出 prompt 與 multi_prompt 只能二選一，不可同時提供。其文件中的 generate_audio 預設為 true，如果你的預算或後製流程預期輸出無聲影片，務必明確設定。

fal 也為圖片轉影片與動作控制提供不同 ID。不要只把字串中的 text-to-video 替換掉就推測其他 ID，請先確認當前模型參考文件。

配額、排隊時間與額度保護

官方平台、WaveSpeedAI、KIE 與 fal 並沒有共用的公開 Kling 配額。並發數、速率限制、額度餘額、失敗任務計費方式與輸出保留期限，都取決於你選擇的接入管道。請把它們當成供應商設定管理，不要寫成名為 KLING_LIMIT 的固定常數。

一位實際使用者比一般化的重試建議更精準地點出了營運風險：

「Kling 會按次生成收費，而且確實有排隊延遲。最先該接上的，是成本／並發上限；否則遇到壞畫面時，一個不停重試的 agent 可能在一夜之間默默燒光你的額度。」— @ukrroot on X

預算與並發防護措施

在允許 agent 或批次 worker 呼叫 Kling 前，先實作以下控制項：

1. 同時執行任務上限：設定供應商專屬的上限，不要每個 prompt 都直接啟動一個任務。
2. 單一任務預算：提交前估算時長、等級、音訊與輸出數量。
3. 重試預算：有選擇地重試傳輸失敗；參數驗證、驗證失敗或額度不足不應重試。
4. 任務帳本：在任何後續請求前先記錄供應商 job ID，避免 worker 重啟後重複提交生成任務。
5. 終態處理政策：除非供應商明確表示可安全重新提交，否則失敗、取消、逾時或刪除的任務都應標記為完成。
6. 額度警報：餘額或預估支出跨過門檻時，停止佇列。
7. 金鑰與輸出安全：將 key 留在伺服器端，若 key 外洩立即輪替，並將完成的影片複製到耐久儲存空間。

5 秒 Standard 測試相較於 15 秒 Pro 或啟用音訊的任務可能很便宜，但「便宜」仍取決於供應商。選擇預設等級前，請先查看即時模型頁面。

上線前該量測哪些數據

每一筆請求都應追蹤以下欄位：

延遲與配額應視為 endpoint 專屬數據；公開來源並未提供跨供應商共用的 SLA。

Kling API 常見問題

Kling 有官方 API 嗎？

有。Kling 設有官方 Open Platform 開發者文件區。官方管道與第三方閘道是不同服務，請在 Kling Open Platform 文件中確認當前憑證、配額與價格。

Kling 有通用的 API endpoint 嗎？

沒有。官方平台、WaveSpeedAI、KIE 與 fal 使用不同的 endpoint 路徑、模型 ID、驗證 header 與回應封裝。請建立供應商 adapter，而非假設 kling-3.0 在所有地方都有效。

該用輪詢還是 webhook？

若供應商支援，正式環境應優先使用 callback 或 webhook；但本機測試與遺漏 callback 的補救仍應保留輪詢。請加入指數退避、總等待時間上限與冪等機制，避免延遲抵達的 callback 產生重複紀錄。

支援哪些片長與長寬比？

多份現行 Kling 3.0 聚合服務文件列出 3–15 秒片段，以及 16:9、9:16、1:1 比例。個別 endpoint 可能不同，因此應依所選模型頁面驗證，而非將這些數值當作第一方通用規格。

啟用音訊會影響成本嗎？

通常可能會。WaveSpeedAI 在其 Kling 3.0 Standard endpoint 文件中列出 1.5× 的聲音倍率，而 fal 與 KIE 則將 audio 或 sound 作為請求參數提供。請查看所選 endpoint 的即時計費頁面，並明確設定該旗標。

為什麼重試會產生額外費用？

即使第一個任務仍在排隊，重試也可能建立第二次生成。請保存 job ID、設定並發上限、只重試暫時性失敗，並在重新提交狀態不明的請求前核對供應商帳務。

第一次接近正式環境的測試，建議只跑一個 5 秒、無聲的 Standard 任務，完整記錄生命週期；確認重複 worker 的處理正確後，再加入 Pro、音訊、多鏡頭或並發功能。