可靈 4.0 API（kling-v4）串接：參數、價格與程式碼

先說答案：可靈 4.0 已在 HopBase 上線，模型 ID 是 kling-v4。它可以用一段文字提示詞，或一張首幀圖片，產生 3 到 30 秒的影片，解析度 720p 或 1080p，畫面比例 16:9、9:16、1:1、21:9 可選。成片一律帶音軌：傳 audio: false 既去不掉聲音，也不會比較便宜。呼叫方式是非同步任務：先 POST https://api.hop-base.com/v1/video/generate 送出，拿到以 kt 開頭的任務 ID，再輪詢 GET /v1/video/tasks/{task_id}，直到狀態變成 completed 或 failed，通常幾分鐘出片。官方牌價 720p 每秒 $0.1471、1080p 每秒 $0.2206，按成片秒數計費，失敗不扣費。參考圖、參考影片和 2K/4K 目前 kling-v4 還不支援。結果連結 24 小時內有效；用的是同一把 HopBase Key 和美元餘額，不需要另外開可靈帳號。

可靈 4.0 新在哪，什麼時候繼續用 3.0

可靈 4.0 於 2026-10-29 在 HopBase 上線。和同一把 Key 可呼叫的可靈 3.0 系列相比，它單支最長可到 30 秒（3.0 是 15 秒），新增 21:9 寬銀幕比例，而且每支成片都有聲音。輸入端反而更單純：只有文字提示詞，加上可選的一張首幀圖。

	kling-v4	kling-v3	kling-v3-omni
長度	3–30 秒	3–15 秒	3–15 秒
解析度	720p / 1080p	720p / 1080p / 2K / 4K	720p / 1080p / 2K / 4K
畫面比例	16:9 / 9:16 / 1:1 / 21:9	16:9 / 9:16 / 1:1	16:9 / 9:16 / 1:1
聲音	一律有聲	有聲 / 無聲可選	有聲 / 無聲可選
圖片輸入	僅首幀	首尾幀，最多 6 張參考圖	首尾幀、參考圖
參考影片	不支援	不支援	支援（feature）
主體 / 多鏡頭 shots	不支援	支援	支援
官方牌價（1080p 有聲）	$0.2206 / 秒	$0.1765 / 秒	$0.1471 / 秒

需要單支超過 15 秒、要 21:9 比例，或希望每支成片都帶聲音、不想管 audio 開關時，選 kling-v4。需要參考圖、參考影片、用自訂主體維持角色一致、做多鏡頭分鏡，或要 2K/4K 時，繼續用 kling-v3 / kling-v3-omni，shots 與主體的用法見可靈 3.0 多鏡頭分鏡指南。畫質高低我們不在這裡下結論，建議用同一段提示詞在兩個模型上各跑一次自行比較。

價格：按成片秒數計費

kling-v4 按成片長度計費，單價取決於你請求的解析度，有聲無聲同價。以下是 kling-v4 模型卡上的官方牌價：

解析度	官方牌價	5 秒	10 秒	30 秒
720p	$0.1471 / 秒	≈ $0.74	≈ $1.47	≈ $4.41
1080p	$0.2206 / 秒	≈ $1.10	≈ $2.21	≈ $6.62

你實際的單價取決於 Key 綁定的分組，以登入後模型目錄顯示為準。只有成功完成的任務才計費，失敗任務一律不扣。任務完成後，回應裡的 usage.cost_usd 就是這筆任務實際從餘額扣掉的金額。可靈其他型號的價格見價格頁。

步驟一（a）：文生影片

可靈所有模型共用同一個端點，用 HopBase Key 作 Bearer 驗證：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v4",
    "prompt": "雨夜霓虹街道，鏡頭緩慢推軌前進，柏油路面倒映燈光，遠處車流聲",
    "duration": 10,
    "resolution": "1080p",
    "aspect_ratio": "21:9"
  }'

逐一說明欄位：

• model：kling-v4。
• prompt：沒有圖片時必填，最長 2,500 個字元。
• duration：整數秒，3 到 30。不傳時閘道預設 5 秒。
• resolution：720p 或 1080p，同時決定價格檔位。不傳時閘道預設 720p。
• aspect_ratio：16:9、9:16、1:1 或 21:9。不傳時閘道不會代填，文生影片建議明確寫上。
• audio：可以不傳，成片一律有聲，價格也不變。

送出成功回傳 202，任務 ID 在頂層 id：

{
  "id": "kt57xYOUR_TASK_ID",
  "object": "video.generation.task",
  "model": "kling-v4",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "1080p_..."
}

步驟一（b）：首幀圖生影片

想讓一張靜態圖動起來，把它放進 images[]，並標 usage: "first_frame"：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v4",
    "prompt": "鏡頭緩緩推近，咖啡杯上冒出熱氣",
    "duration": 8,
    "resolution": "720p",
    "images": [
      { "url": "https://cdn.example.com/coffee.png", "usage": "first_frame" }
    ]
  }'

• 成片比例跟隨輸入圖，aspect_ratio 不生效。想要直式成片，先把圖裁成 9:16。
• 每個圖片項目必須且只能有 url 或 file_id 其中之一。url 必須是公開可存取的 http(s) 絕對網址；相對路徑、file://、內網或迴環 IP、帶帳號密碼的 URL 在送出時就會被拒。
• 每張圖都必須寫 usage。kling-v4 只接受首幀，傳 usage: "reference" 會回傳 400：model kling-v4 does not support reference-based generation。

步驟二：輪詢到任務結束

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

status 從 queued 到 processing，最後停在 completed 或 failed。只有這兩個是終態，其他值一律當作還在執行。完成時長這樣：

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "1080p_...", "billed_seconds": 10, "cost": ..., "cost_usd": 2.206, "currency": "CNY" }
}

outputs 裡是 api.hop-base.com 上的簽名連結，從任務完成起 24 小時有效；再次查詢回傳同一個連結、不會延長，過期回傳 410，所以拿到後請立刻轉存到自己的儲存空間。usage.cost_usd 是從美元餘額實際扣掉的金額，cost 是同一筆費用的人民幣表示。

任務失敗時查詢仍回傳 HTTP 200，status 為 failed，並帶穩定的 error.code：

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "failed",
  "error": { "code": "input_sensitive", "message": "..." }
}

完整 Python 範例

以下腳本送出一筆文生影片任務，每 10 秒輪詢一次，完成後把 MP4 下載到本機：

import time
import requests

API = "https://api.hop-base.com/v1"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

resp = requests.post(f"{API}/video/generate", headers=HEADERS, json={
    "model": "kling-v4",
    "prompt": "陽光下的森林小溪，一艘紙船順流漂下，鳥鳴和流水聲",
    "duration": 10,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
})
resp.raise_for_status()
task_id = resp.json()["id"]
print("submitted", task_id)

while True:
    task = requests.get(f"{API}/video/tasks/{task_id}", headers=HEADERS).json()
    status = task["status"]
    if status == "completed":
        url = task["outputs"][0]
        with requests.get(url, stream=True) as r:
            r.raise_for_status()
            with open(f"{task_id}.mp4", "wb") as f:
                for chunk in r.iter_content(chunk_size=1 << 20):
                    f.write(chunk)
        print("saved", f"{task_id}.mp4", "charged $", task["usage"]["cost_usd"])
        break
    if status == "failed":
        err = task.get("error", {})
        raise RuntimeError(f'{err.get("code")}: {err.get("message")}')
    time.sleep(10)

可靈的請求沒有回呼（webhook）欄位，追蹤任務只能靠輪詢。建立後 2 小時仍未完成的任務會被標記為失敗（error.code 為 timeout），不計費；任務無法取消。如果你同時使用多家影片模型，一個 API 串接 Seedance、可靈、海螺和萬相裡有一段三家通用的輪詢程式。

常見錯誤

請求內容以嚴格模式解析，送出階段的錯誤會立即回傳，不建立任務、不扣費：

你送了什麼	error.message
duration 超出 3–30	model kling-v4 supports 3 to 30 seconds, got 40
圖片帶 usage: "reference"	model kling-v4 does not support reference-based generation
圖片沒寫 usage	images[0].usage is required for standard Kling video requests
resolution 傳 "2k" 或 "4k"	model "kling-v4" does not support billing bucket "..." for this request
帶了 OpenAI 習慣的欄位，例如 size	request body does not match the JSON contract: json: unknown field "size"
既沒有提示詞也沒有圖片	prompt and input media cannot both be empty

回傳 402、code 為 insufficient_balance，表示餘額扣除進行中任務與本次任務的預估費用後不足；任務結束後預扣會自動釋放。

素材本身由可靈在任務執行時檢查，不在送出時檢查。圖片無法下載、格式或尺寸不符時，任務會先被接受，幾分鐘後以 reference_input_invalid 失敗；提示詞或圖片被內容審核擋下時以 input_sensitive 失敗。這些失敗都不計費。完整錯誤對照見可靈影片 API 文件。

常見問題

可靈 4.0 的模型 ID 是什麼？

kling-v4。送出付費任務前，先用你的 Key 呼叫 GET /v1/models，確認它在 Key 綁定的分組裡。

可靈 4.0 一支影片最長幾秒？

每個任務 3 到 30 秒，整數秒。不傳 duration 時預設 5 秒。

可靈 4.0 支援 2K 或 4K 嗎？

暫不支援，kling-v4 只有 720p 和 1080p。需要 2K/4K 請用 kling-v3 或 kling-v3-omni。

可以關掉聲音嗎？

不行。即使傳 audio: false，成片也帶音軌，價格也一樣。需要無聲檔案的話，下載後自行移除音軌。

可靈 4.0 支援參考圖或參考影片嗎？

不支援。它只接受文字提示詞和可選的一張首幀圖。需要參考圖、參考影片、自訂主體或多鏡頭分鏡，請用 kling-v3-omni 或 kling-v3。

圖生影片時 aspect_ratio 為什麼不生效？

傳了首幀圖時，成片比例跟隨輸入圖，aspect_ratio 會被忽略。送出前先把圖裁成想要的比例。

產生要多久？

通常幾分鐘。建議每 5 到 10 秒輪詢一次。建立 2 小時後仍未完成的任務以 timeout 失敗，不扣費。

一支 10 秒 1080p 的可靈 4.0 影片多少錢？

按官方牌價，10 × $0.2206 ≈ $2.21。每筆任務的實際扣費在 usage.cost_usd 裡回傳，也會出現在使用紀錄中。

怎麼開通？

在 HopBase 控制台建立 API Key，綁定包含可靈的分組，再用 GET /v1/models 確認能看到 kling-v4。同一把 Key 只要分組包含，也能呼叫可靈動作控制、可靈數位人，以及影片總覽裡的其他影片模型。