> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling Videos Generation API 對接說明 > Kling video generation 集成指南 - XHuoAPI 本文將介紹一種 Kling Videos Generation API 對接說明，它是可以透過輸入自訂參數來生成Kling官方的影片。 ## 申請流程 要使用 API，需要先到 [Kling Videos Generation API](https://api.xhuoapi.ai/documents/3b921a16-a411-4557-8335-53f21d3f9e46) 對應頁面申請對應的服務，進入頁面之後，點擊「Acquire」按鈕，如圖所示： ![](https://cdn.xhuoapi.ai/q6ytrc.png) 如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。 在首次申請時會有免費額度贈送，可以免費使用該 API。 ## 基本使用 首先先了解下基本的使用方式，就是輸入提示詞 `prompt`、 生成行為 `action`、首幀參考圖片 `start_image_url` 以及模型 `model`，便可獲得處理後的結果，首先需要簡單地傳遞一個 `action` 欄位，它的值為 `text2video`，它主要包含三種行為：文生影片（`text2video`）、圖生影片（`image2video`）、擴展影片（`extend`），然後我們還需要輸入模型 `model`，目前主要有 `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, `kling-video-o1` 模型，具體的內容如下：

可以看到這裡我們設定了 Request Headers，包括： * `accept`：想要接收怎樣格式的響應結果，這裡填寫為 `application/json`，即 JSON 格式。 * `authorization`：調用 API 的密鑰，申請之後可以直接下拉選擇。 另外設定了 Request Body，包括： * `model`：生成影片的模型，主要有 `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, `kling-video-o1` 模型。 * `mode`：生成影片的模式，可選值為標準模式 `std`、極速模式 `pro` 和原生 4K 模式 `4k`。其中 `4k` 僅支援 `kling-v3` 和 `kling-v3-omni`，且與 `camera_control`（運鏡控制）不相容。 * `action`：此次影片生成任務的行為，主要包含三種行為，分別為：文生影片（`text2video`）、圖生影片（`image2video`）、擴展影片（`extend`）。 * `start_image_url`：當選擇圖生影片行為 `image2video` 就必須需要上傳的首幀參考圖片連結。 * `end_image_url`：圖生影片時可選，指定尾幀。 * `duration`：影片時長，單位秒。對於 `kling-v3` 和 `kling-v3-omni` 模型支援靈活時長 3-15 秒（整數），其他模型支援 5 或 10 秒。 * `generate_audio`：是否同步生成音訊，可選，布林值。支援 `kling-v3`、`kling-v3-omni` 以及 `kling-v2-6`（僅 pro 模式）。預設為 `false`。 * `aspect_ratio`：影片寬高比，可選，支援 `16:9`、`9:16`、`1:1`，預設 `16:9`。 * `cfg_scale`：相關性強度，範圍 \[0,1]，越大越貼合提示詞。 * `camera_control`：可選，控制相機運動的物件參數，支援 type/simple 預設以及 horizontal、vertical、pan、tilt、roll、zoom 等配置。 * `negative_prompt`：可選，不希望出現的反向提示詞，最多 200 字元。 * `element_list`：主體參考列表，只適用模型`kling-video-o1`，該參數的具體的使用方式參考[官網文件](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z)。 * `video_list`：參考影片，透過URL方式取得，只適用模型`kling-video-o1`,該參數的具體的使用方式參考[官網文件](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z)。 * `prompt`：提示詞。 * `callback_url`：需要回調結果的URL。 選擇之後，可以發現右側也生成了對應程式碼，如圖所示：

點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果： ```json theme={null} { "success": true, "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0" } ``` 回傳結果一共有多個欄位，介紹如下： * `success`，此時影片生成任務的狀態情況。 * `task_id`，此時影片生成任務ID。 * `video_id`，此時影片生成任務的影片ID。 * `video_url`，此時影片生成任務的影片連結。 * `duration`，此時影片生成任務的影片長度。 * `state`，此時影片生成任務的狀態。 可以看到我們得到了滿意的影片資訊，我們只需要根據結果中 `data` 的影片連結地址取得生成的Kling影片即可。 另外如果想生成對應的對接程式碼，可以直接複製生成，例如 CURL 的程式碼如下： ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-v1", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }' ``` ## 模型能力矩陣 不同模型對參數的支援情況差異較大。以下矩陣整理自 [Kling 官方 video models 文件](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels)，呼叫前請先核對當前 `model` / `mode` / `duration` 組合是否支援你所需的功能，否則上游會回傳 `model/mode/duration(...) is not supported with image_tail` 等錯誤。 | 模型 | 模式 | `end_image_url`（首尾幀） | `generate_audio`（伴音） | `camera_control`（運鏡） | 備註 | | ------------------- | -------------- | -------------------- | -------------------- | -------------------- | -------------------------------------------- | | `kling-v1` | std / pro | ✅ 僅 `duration=5` | ❌ | ✅ 僅 `duration=5` | `extend` 不支援 `negative_prompt` 與 `cfg_scale` | | `kling-v1-6` | std | ❌ | ❌ | ❌ | 多圖生影片、`extend` 全模式可用 | | `kling-v1-6` | pro | ✅ | ❌ | ❌ | | | `kling-v2-master` | — | ❌ | ❌ | ❌ | 單一模式，僅 `duration=5/10` | | `kling-v2-1-master` | — | ❌ | ❌ | ❌ | 單一模式，僅 `duration=5/10` | | `kling-v2-5-turbo` | std | ❌ | ❌ | ❌ | | | `kling-v2-5-turbo` | pro | ✅ | ❌ | ❌ | | | `kling-v2-6` | std | ❌ | ❌ | ❌ | | | `kling-v2-6` | pro | ✅ | ✅ | ❌ | 唯一同時支援伴音的非 v3 模型 | | `kling-v3` | std / pro | ✅ | ✅ | ✅ | `duration` 範圍 3–15 秒 | | `kling-v3` | 4k | ✅ | ✅ | ❌ | 4K 模式與運鏡不相容 | | `kling-v3-omni` | std / pro / 4k | ✅ | ✅ | ❌ | | | `kling-video-o1` | std / pro | ✅ | ❌ | ❌ | 僅支援 `duration=5/10` | 注意事項： * `mode=4k` 僅 `kling-v3` 與 `kling-v3-omni` 支援；並且與 `camera_control`（運鏡）互斥。 * `end_image_url` 只能在 `action=image2video` 時配合 `start_image_url` 使用。僅傳 `end_image_url`（無 `start_image_url`）會被拒絕。 * `kling-v3` / `kling-v3-omni` 接受任意 3–15 秒的整數 `duration`；其餘模型只接受 5 或 10。 * `generate_audio` 預設 `false`。僅 `kling-v3`、`kling-v3-omni` 和 `kling-v2-6`（pro 模式）支援。 ## 擴展影片功能 如果想對已經生成的Kling影片進行繼續生成的話，可以將參數 `action` 設定為 `extend` ，並且輸入需要繼續生成影片的 ID，影片 ID 的取得是根據基本使用來取得，如下圖所示：

這時候可以看到影片的 ID 為： ``` "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c" ``` > 注意，這裡的影片中 `video_id` 是生成後影片的 ID，如果你不知道如何生成影片，可以參考上文的基本使用來生成影片。 接下來我們要必須填下一步需要擴展的提示詞來自訂生成影片，就可以指定如下內容： * `model`：生成影片的模型，主要有 `kling-v1` 、`kling-v1-5` 和 `kling-v1-6` 模型。 * `mode`：生成影片的模式，可選值為標準模式 `std`、極速模式 `pro` 和原生 4K 模式 `4k`（僅 `kling-v3` 和 `kling-v3-omni` 支援，與運鏡控制不相容）。 * `duration`：此次影片生成任務的影片時長，主要包含5s和10s。 * `start_image_url`：當選擇圖生影片行為 `image2video` 就必須需要上傳的首幀參考圖片連結。 * `prompt`：提示詞。 填寫範例如下：

填寫完畢之後自動生成了程式碼如下：

對應的 Python 程式碼： ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/kling/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "extend", "model": "kling-v1", "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.", "duration": 10 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 點擊執行，可以發現會得到一個結果，如下： ```json theme={null} { "success": true, "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4", "duration": "9.6", "state": "succeed", "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23" } ``` 可以看出，結果內容與上文的是一致的，這也就實現影片的擴展影片功能。 ## 非同步回調 由於 Kling Videos Generation API生成的時間相對較長，大約需要 1-2 分鐘，如果 API 長時間無回應，HTTP 請求會一直保持連線，導致額外的系統資源消耗，所以本 API 也提供了非同步回調的支援。 整體流程是：用戶端發起請求的時候，額外指定一個 `callback_url` 欄位，用戶端發起 API 請求之後，API 會立刻回傳一個結果，包含一個 `task_id` 的欄位資訊，代表當前的任務 ID。當任務完成之後，生成影片的結果會透過 POST JSON 的形式發送到用戶端指定的 `callback_url`，其中也包括了 `task_id` 欄位，這樣任務結果就可以透過 ID 關聯起來了。 下面我們透過範例來了解下具體怎麼操作。 首先，Webhook 回調是一個可以接收 HTTP 請求的服務，開發者應該替換為自己搭建的 HTTP 伺服器的 URL。此處為了方便演示，使用一個公開的 Webhook 範例網站 [https://webhook.site/，打開該網站即可得到一個](https://webhook.site/，打開該網站即可得到一個) Webhook URL，如圖所示： ![](https://cdn.xhuoapi.ai/tbcnai.png) 將此 URL 複製下來，就可以作為 Webhook 來使用，此處的範例為 `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`。 接下來，我們可以設定欄位 `callback_url` 為上述 Webhook URL，同時填入相應的參數，具體的內容如圖所示：

點擊執行，可以發現會立即得到一個結果，如下： ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` 稍等片刻，我們可以在 `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3` 上觀察到生成影片的結果，如圖所示： ![](https://cdn.xhuoapi.ai/zv5u2q.png) 內容如下： ```json theme={null} { "success": true, "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` 可以看到結果中有一個 `task_id` 欄位，其他的欄位都和上文類似，透過該欄位即可實現任務的關聯。 ## 錯誤處理 在呼叫 API 時，如果遇到錯誤，API 會回傳相應的錯誤代碼和資訊。例如： * `400 token_mismatched`：Bad request，可能由於缺少或無效參數。 * `400 api_not_implemented`：Bad request，可能由於缺少或無效參數。 * `401 invalid_token`：Unauthorized，無效或缺少授權令牌。 * `429 too_many_requests`：Too many requests，您已超過速率限制。 * `500 api_error`：Internal server error，伺服器端出錯。 ### 錯誤回應範例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 結論 透過本文檔，您已經了解了如何使用 Kling Videos Generation API 可透過輸入提示詞以及首幀參考圖片來生成影片。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支援團隊。