Kling Videos Generation API 串接說明

本文將介紹一種 Kling Videos Generation API 串接說明，它可以透過輸入自訂參數來生成 Kling 官方的影片。

申請流程

要使用 Kling Videos Generation API，首先到 Ace Data Cloud 控制台取得您的 API Token，以備使用。

如果您尚未登入或註冊，會自動跳轉至登入頁面邀請您註冊和登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台儲值通用餘額。

📘 完整文件：Kling Videos Generation 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-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-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 秒整數時長；kling-o1 僅支援 5 秒；其他模型支援 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 字元。
image_list：Omni 參考圖片清單，適用模型 kling-o1 和 kling-v3-omni，用法見下文「Omni 全能參考」。
video_list：Omni 參考影片清單（支援影片編輯），適用模型 kling-o1 和 kling-v3-omni，用法見下文「Omni 全能參考」。
prompt：提示詞。
callback_url：需要回呼結果的 URL。
async：可選，設為 true 時介面立即回傳 task_id，無需提供 callback_url，隨後透過對應的任務查詢介面輪詢取得結果。

選擇之後，可以發現右側也生成了對應程式碼，如圖所示：

點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果：

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

回傳結果一共有多個欄位，介紹如下：

success，此時影片生成任務的狀態情況。
task_id，此時影片生成任務 ID。
video_id，此時影片生成任務的影片 ID。
video_url，此時影片生成任務的影片連結。
duration，此時影片生成任務的影片時長。
state，此時影片生成任務的狀態。

可以看到我們取得了滿意的影片資訊，我們只需要根據結果中 data 的影片連結地址取得生成的 Kling 影片即可。另外如果想生成對應的串接程式碼，可以直接複製生成，例如 CURL 的程式碼如下：

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "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."
}'

模型能力矩陣

O1 與 Omni 參考影片計費

kling-o1 按模式及是否提供 video_list 計費。以下是 5 秒成片的價格：

模式	無參考影片	有參考影片
std	4.005 Credits	6.010 Credits
pro	5.340 Credits	8.010 Credits
`kling-o1` 和 `kling-v3-omni` 帶參考影片的成功請求按計費秒數收費：std 為 1.202 Credits/秒，pro 為 1.602 Credits/秒。例如 std 模式生成 5 秒為 6.010 Credits。省略 `video_list` 不會觸發參考影片檔；`image_list`、首幀和尾幀圖片也不屬於參考影片。參考影片不能與 `generate_audio=true` 同時使用。

refer_type=base（預設）的影片編輯可能跟隨參考影片片長，最終按實際成片時長四捨五入到整數秒計費：例如 5.708 秒按 6 秒，5.041 秒按 5 秒。refer_type=feature 使用請求的 duration。回應中的 usage.reference_video_seconds 給出最終計費秒數；請求時的估算價格可能與最終扣費不同。不同模型對參數的支援情況差異較大。以下矩陣整理自 Kling 官方 video models 文件，呼叫前請先核對目前 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-o1`	std / pro	✅	❌	❌	僅支援 `duration=5`

注意事項：

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；kling-o1 僅接受 5；其餘模型只接受 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 程式碼：

import requests

url = "https://api.acedata.cloud/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)

點擊執行，可以發現會得到一個結果，如下：

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

可以看出，結果內容與上文的是一致的，這也就實現影片的擴展影片功能。

Omni 全能參考（影片編輯 / 參考影片 / 多圖參考）

kling-o1 與 kling-v3-omni 是兩個獨立模型，二者都支援「全能參考」能力。在文生影片（action=text2video）基礎上，可額外傳入參考圖片或參考影片，實現多圖參考、參考影片以及直接編輯已有影片。 核心約定：參考素材必須在 prompt 中以 <<<image_1>>>、<<<video_1>>> 的形式（序號從 1 開始）引用 image_list / video_list 中對應位置的素材，模型才會套用這些參考。若只傳素材而不在提示詞中引用，素材會被忽略。

安全說明：目前 API 不開放 element_list。Kling Element Library 的 ID 不是租戶隔離的，在提供租戶隔離的 Element Management API 之前，請使用 image_list 傳入主體參考圖。

Omni 請求不支援 negative_prompt、cfg_scale 或 camera_control，也不能使用 mode=4k。包含參考影片時，generate_audio 必須為 false。 video_list 用於傳入參考影片，是本能力最常用的場景，陣列元素欄位如下：

video_url：參考影片連結，不可為空。最多 1 個 MP4/MOV 影片，檔案大小 ≤200MB，影格率 24–60fps。kling-o1 要求時長 3–10 秒、寬和高各 700–2160px；kling-v3-omni 要求時長 3–15.5 秒、寬和高各 700–4553px、總像素 ≤8,294,400、寬高比 0.4–2。
refer_type：參考類型，可選 base（預設，待編輯的基礎影片，即「直接對影片進行編輯」，可增刪/修改元素、改構圖、換風格、換顏色、換天氣等）或 feature（特徵參考，參考其風格 / 運鏡 / 續拍下一鏡頭）。
keep_original_sound：是否保留原影片音訊，可選 yes（保留）或 no（移除）。

注意：存在參考影片時，generate_audio 需為 false。refer_type=base 的影片不可再指定首幀 / 尾幀。

對已有影片進行編輯（把影片改成動漫風格）的 CURL 範例如下：

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

多圖參考（`image_list`）

image_list 用於傳入參考圖片（元素 / 場景 / 風格等），陣列元素欄位如下：

image_url：參考圖片連結，不可為空。要求：格式 .jpg/.jpeg/.png；檔案大小 ≤10MB；最短邊 ≥300px；寬高比 1:2.5 ~ 2.5:1。
type：可選。不傳時作為純參考圖；傳 first_frame / end_frame 時分別作為首幀 / 尾幀（等同於 start_image_url / end_image_url）。

使用時需在 prompt 中以 <<<image_1>>>、<<<image_2>>> 引用。數量限制：不存在參考影片時參考圖片 ≤ 7；存在參考影片時參考圖片 ≤ 4。僅傳首 / 尾幀時也可直接用 start_image_url / end_image_url，但尾幀必須與首幀一起使用。

注意：若同時傳入 start_image_url / end_image_url 與 image_list，首 / 尾幀會排在 image_list 之前，可能影響 <<<image_N>>> 的序號對應關係。建議二選一：需要首 / 尾幀時直接在 image_list 中用 type 指定，不要與 start_image_url / end_image_url 混用。

多圖參考生成影片的 CURL 範例：

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

非同步回呼

由於 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/，開啟該網站即可得到一個 Webhook URL，如圖所示：

將此 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 上觀察到生成影片的結果，如圖所示：

內容如下：

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

可以看到結果中有一個 task_id 欄位，其他的欄位都和上文類似，透過該欄位即可實現任務的關聯。

錯誤處理

在呼叫 API 時，如果遇到錯誤，API 會傳回相應的錯誤代碼和資訊。例如：

400 token_mismatched：錯誤請求，可能由於缺少或無效的參數。
400 api_not_implemented：錯誤請求，可能由於缺少或無效的參數。
401 invalid_token：未授權，無效或缺少授權權杖。
429 too_many_requests：請求過多，您已超過速率限制。
500 api_error：內部伺服器錯誤，伺服器上發生了問題。

錯誤回應範例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

透過本文檔，您已經瞭解了如何使用 Kling Videos Generation API，可透過輸入提示詞以及首幀參考圖片來生成影片。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。

Kling 3.0 Turbo

model="kling-v3-turbo" 支援文字生成影片和首幀圖片生成影片，時長為 3–15 秒的整數。mode="std" 輸出 720p，mode="pro" 輸出 1080p。該模型自帶原生音訊，不提供關閉開關；省略 generate_audio 或設定為 true。該模型不支援尾幀、運鏡物件、獨立負向提示詞或 cfg_scale。請在 prompt 中直接描述需要或避免出現的內容。

多鏡頭影片

kling-v3 和 kling-v3-omni 支援 multi_shot=true。shot_type="intelligence" 根據 prompt 自動分鏡；shot_type="customize" 透過 multi_prompt 提供 1–6 個分鏡，每項包含從 1 連續遞增的 index、最多 512 字的 prompt 和至少 1 秒的整數 duration。所有分鏡時長之和必須等於總 duration。自訂分鏡不使用全域 prompt。多鏡頭按所選模型、畫質、音訊設定和總時長計費。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Kling Videos Generation API 串接說明

申請流程

基本使用

模型能力矩陣

O1 與 Omni 參考影片計費

擴展影片功能

Omni 全能參考（影片編輯 / 參考影片 / 多圖參考）

多圖參考（`image_list`）

非同步回呼

錯誤處理

錯誤回應範例

結論

Kling 3.0 Turbo

多鏡頭影片

​申請流程

​基本使用

​模型能力矩陣

​O1 與 Omni 參考影片計費

​擴展影片功能

​Omni 全能參考（影片編輯 / 參考影片 / 多圖參考）

​參考影片與影片編輯（video_list）

​多圖參考（image_list）

​非同步回呼

​錯誤處理

​錯誤回應範例

​結論

​Kling 3.0 Turbo

​多鏡頭影片

申請流程

基本使用

模型能力矩陣

O1 與 Omni 參考影片計費

擴展影片功能

Omni 全能參考（影片編輯 / 參考影片 / 多圖參考）

參考影片與影片編輯（`video_list`）

多圖參考（`image_list`）

非同步回呼

錯誤處理

錯誤回應範例

結論

Kling 3.0 Turbo

多鏡頭影片