Skip to content
上新Nano Banana 2.1 已上線：Google 新一代生圖模型，單張低至 $0.0336，原生 4K，約上一代半價查看模型
HopBase
← 返回 Blog

可靈動作控制 API 串接：請求格式、計費與失敗原因

HopBase 2026年10月29日 17 分鐘閱讀

先說答案：可靈「動作控制」（Motion Control）的輸入是一張人物圖加一段動作影片，輸出是圖中人物照著影片動作動起來的成片。在 HopBase 上有兩個模型可用：kling-v3-motion-control，支援 720p / 1080p / 2K / 4K；kling-v2-6-motion-control，支援 720p / 1080p。呼叫方式跟其他可靈模型相同，都是非同步任務：先 POST https://api.hop-base.com/v1/video/generate 送出，再輪詢 GET /v1/video/tasks/{task_id}。請求裡人物圖和動作影片各放一個；不要傳 duration，成片長度由動作影片決定。唯一的擴充參數是 extra.character_orientation，值為 image 或 video。計費依成片秒數，任務失敗不收費，結果連結 24 小時內有效。最常出問題的是動作影片本身：畫面中必須是真人，而且從頭到腰的上半身要完整、清楚。

動作控制是什麼？跟數位人、對嘴型怎麼選

可靈有三條讓人物動起來的流程，各自適合不同需求：

模型輸入動的是什麼成片長度
kling-v3-motion-control / kling-v2-6-motion-control1 張人物圖 + 1 段動作影片全身照著影片動作做等於動作影片長度
kling-avatar1-5 張人物圖 + 1 段音訊臉部和嘴型隨音訊變化等於音訊長度
kling-lip-sync既有影片 + 新音訊只改嘴型，對上新台詞等於來源影片長度

如果手上已經有一段動作素材，例如舞蹈、商品展示的手勢、走秀或主持人的肢體動作，想換成另一個角色來演（品牌吉祥物、換了服裝的模特兒、AI 生成的角色），就用動作控制。如果角色只需要開口說話，用數位人或對嘴型比較合適，詳見《可靈數位人 API 實戰》。

v3 還是 v2.6：解析度與官方牌價

兩個模型都依成片秒數計費，單價隨解析度不同。下表是各模型卡上公布的官方牌價；你的實際費率取決於所屬群組，以登入後模型目錄顯示的為準：

模型720p1080p2K4K
kling-v3-motion-control$0.1324/秒$0.1765/秒$0.2647/秒$0.3971/秒
kling-v2-6-motion-control$0.0735/秒$0.1176/秒——

舉例來說，用 kling-v3-motion-control 產生 10 秒 1080p 成片，以牌價計算是 10 × $0.1765，約 $1.77。價格頁上同一級距的人民幣牌價為 ¥1.20/秒。打樣或大量產出 720p 用 v2.6，需要 2K / 4K 再用 v3。各級距價格見模型卡 kling-v3-motion-control 和 kling-v2-6-motion-control。

步驟一：送出任務

請求送到可靈影片的統一端點。動作控制情境裡每個素材的角色是固定的，所以人物圖不寫 usage，動作影片也不寫 reference_type：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "prompt": "照著影片中的舞蹈動作跳",
    "resolution": "1080p",
    "images": [{ "url": "https://cdn.example.com/character.png" }],
    "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
    "extra": { "character_orientation": "video" }
  }'

各欄位說明：

  • images：只放一項，就是要做動作的人物。
  • videos：只放一項，作為動作來源。keep_original_sound: true 會保留原影片的音軌。動作控制本身不產生聲音。
  • extra.character_orientation：選填，值為 image 或 video。兩個值的差別主要在鏡頭和長度上限。我們用同一張人物圖和同一段帶 180° 轉身的動作影片實測，兩種模式下角色都會跟著影片轉身、背對鏡頭；image 維持人物圖的構圖和機位，背景幾乎不動，動作影片最長 10 秒；video 讓鏡頭跟著動作影片重新取景、推拉，動作影片最長 30 秒。不傳時 HopBase 預設以 video 處理。這是動作控制唯一接受的 extra 鍵，傳其他鍵會回傳 400。
  • resolution：v3 支援 720p / 1080p / 2k / 4k，v2.6 支援 720p / 1080p，同時決定計費級距。
  • duration：不要傳。長度由輸入影片決定，傳了會報 duration of model ... is determined by the input media; do not pass duration。

每個素材項只能在 url 和 file_id 中擇一。url 必須是公開網路可直接存取的絕對 http(s) 位址；相對路徑、file://、內網或回送位址、內含帳密的連結，送出時就會被拒絕。送出成功回傳 202，任務 ID 形如 kt57x…。

步驟二：輪詢到任務結束

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

狀態依序是 queued → processing，最後是 completed 或 failed。只有後兩者是終態，其他值都視為仍在執行。任務完成時的回應如下：

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

outputs 是 api.hop-base.com 上的簽章連結，從任務完成起 24 小時內有效，重複查詢不會延長，請盡快轉存到自己的儲存空間。usage.cost_usd 是這個任務實際扣的金額。Python 最小輪詢範例：

import time, requests

API = "https://api.hop-base.com/v1"
H = {"Authorization": "Bearer sk-你的金鑰"}

task = requests.post(f"{API}/video/generate", headers=H, json={
    "model": "kling-v3-motion-control",
    "prompt": "照著影片中的舞蹈動作跳",
    "resolution": "1080p",
    "images": [{"url": "https://cdn.example.com/character.png"}],
    "videos": [{"url": "https://cdn.example.com/dance.mp4"}],
    "extra": {"character_orientation": "video"},
}).json()

while True:
    t = requests.get(f"{API}/video/tasks/{task['id']}", headers=H).json()
    if t["status"] == "completed":
        print(t["outputs"][0]); break
    if t["status"] == "failed":
        raise RuntimeError(f"{t['error'].get('code')}: {t['error']['message']}")
    time.sleep(5)

可靈的請求裡沒有回呼（webhook）欄位，只能用輪詢追蹤進度。任務建立 2 小時後仍未完成，會被標記為失敗（error.code 為 timeout），不收費。任務送出後無法取消。

動作影片：最容易出錯的一步

送出時，HopBase 只檢查請求結構：素材數量、欄位名稱、URL 格式和解析度。素材本身的格式、大小、解析度、長度和內容，是可靈在任務執行期間才檢查。所以不合規的影片會先被受理，幾分鐘後才失敗。動作控制最常見的失敗是這一條：

error.code: reference_input_invalid
the motion reference video was rejected: no complete human upper body was detected in it;
use a video in which a real person's upper body (head to waist) is clearly visible, then submit again

準備動作影片時請注意：

  • 必須是真人入鏡。動物、怪物等非真人角色會被拒絕。
  • 整段影片中，從頭到腰都要在畫面內，而且不能被遮住。特寫裁切、桌子或道具擋住軀幹、嚴重的動態模糊，都容易失敗。
  • 素材放在伺服器能穩定下載的地方。自己的物件儲存或 CDN 比免費圖床可靠，不少免費圖床會封鎖機房 IP。
  • 動作影片有多長，成片就有多長，費用也跟著變。送出前先剪掉不需要的部分。
  • 注意長度上限：character_orientation 為 image 時動作影片不能超過 10 秒，為 video（預設）時不能超過 30 秒。超過上限的任務會在送出後約半分鐘失敗，error.code 為 invalid_request，不收費。實測 12 秒的影片在 image 模式下被拒，在 video 模式下正常產出 12 秒成片；31 秒的影片在 video 模式下也被拒。
  • 成片畫面比例跟著人物圖，不跟著動作影片。實測 9:16 直式動作影片搭配一張約 5:6 的人物圖，成片是 864×1040。想要直式成片，就準備直式構圖的人物圖。image 模式的成片可能比素材略短，實測 5 秒素材產出 4.8 秒，以 4 秒計費。

任務失敗不收費，素材不合格只會多花一點時間。

送出階段的錯誤

送出階段的錯誤不會建立任務，也不收費。以下是動作控制特有的錯誤與原文：

你送了什麼error.message
圖片 0 張或 2 張，或沒有影片motion control requires exactly 1 motion video and 1 character image
人物圖帶了 usagemotion control images[0] does not accept usage; the character image role is fixed by the scene
影片帶了 reference_typemotion control videos[0] does not accept reference_type; the motion video role is fixed by the scene
朝向不是 image / videoextra.character_orientation must be image or video
傳了 durationduration of model kling-v3-motion-control is determined by the input media; do not pass duration
照 OpenAI 習慣傳了 size 等欄位request body does not match the JSON contract: json: unknown field "size"

如果回傳 402，且 code 為 insufficient_balance，表示可用餘額扣除執行中任務的預估費用後，不足以支付這一筆。任務結束後，預留的金額會自動釋放。完整錯誤表見 可靈影片串接文件。

放進正式產線

常見做法是：每個動作只拍一段乾淨的素材，例如開箱展示、打招呼或一個舞蹈節拍，再用這段素材搭配多張不同的人物圖，換模特兒、換服裝、換品牌角色。每次的成本就是素材秒數乘以單價，很好估算。同一把金鑰只要包含對應群組，也能呼叫可靈文生影片、用 MiniMax 語音合成做配音，以及用對話模型撰寫提示詞。金鑰能用哪些模型，以 GET /v1/models 的回傳為準。

常見問題

動作控制可以指定長度嗎？

不行。必須省略 duration，傳了會回傳 400。成片長度等於動作影片長度，想控制長度和成本，就先把素材剪短。

動作影片最長可以多長？

取決於 extra.character_orientation：image 最長 10 秒，video（預設）最長 30 秒。超過上限的任務會在執行約半分鐘後以 invalid_request 失敗，不收費。需要更長的成片，就把動作拆成幾段分別生成再接起來。

character_orientation 該選 image 還是 video？

兩種模式下角色都會照著影片轉身。想保留人物圖的機位和構圖，例如固定機位的產品展示，用 image，動作影片控制在 10 秒內；想連鏡頭運動一起複製，或素材超過 10 秒，用 video。

動作控制會產生聲音嗎？

不會產生新的聲音。想保留動作影片的原聲，把 videos[0].keep_original_sound 設為 true。不要寫在 extra 裡，extra.keep_original_sound 會被拒絕。

任務送出成功，為什麼幾分鐘後又失敗？

可靈是在任務執行期間才檢查素材。最常見的原因是動作影片裡沒有清楚完整的真人上半身（reference_input_invalid），其次是連結無法下載，或內容審核未通過（input_sensitive）。失敗的任務不收費。

kling-v3-motion-control 和 kling-v2-6-motion-control 有什麼差別？

v3 支援 720p、1080p、2K 和 4K；v2.6 只支援 720p 和 1080p，但單價較低：720p 為 $0.0735/秒，1080p 為 $0.1176/秒，v3 對應是 $0.1324/秒和 $0.1765/秒。兩者的請求格式完全相同。

成片可以下載多久？

從任務完成起 24 小時內。重複查詢拿到的是同一個連結，不會延長；連結過期後存取會回傳 410。

怎麼開通？

在 HopBase 主控台建立金鑰，並選擇包含可靈模型的群組，再呼叫 GET /v1/models 確認清單裡有 kling-v3-motion-control。牌價見價格頁。

教程可靈