可靈影片與生圖 API

HopBase 透過騰訊雲點播（VOD）AIGC 閘道接入可靈。介面是非同步的：先提交任務，再輪詢 HopBase 任務 ID。請使用已配置可靈 VOD 帳號的分組金鑰，正式產生付費任務前先用 GET /v1/models 確認目前金鑰實際返回的完整模型 ID。

騰訊雲點播帳號

可靈帳號需要配置騰訊雲點播的 SecretId、SecretKey 和點播主應用的數字 SubAppId。region 對 VOD 通常可留空。金鑰只填寫在 HopBase 帳號配置中，不要放進客戶端請求、範例或程式碼倉庫；客戶端仍使用 HopBase 的 https://api.hop-base.com/v1，不要把騰訊 VOD 或 TokenHub 位址當作客戶 Base URL。

介面

所有請求使用 Authorization: Bearer sk-你的金鑰 和 Content-Type: application/json。請求體採用嚴格 JSON 契約：未知欄位、第二個 JSON 值、頂層 image_url / video_url 和未驗證的巢狀欄位會在呼叫騰訊前拒絕。

模型矩陣

可靈生圖模型 ID 包括 kling-image-v3、kling-image-v3-omni、kling-image-o1、kling-image-v2-1、kling-image-v2-1-i2i、kling-image-v2-1-multi-ref 和 kling-image-expand。生圖走圖片介面，n 支援 1-9，按實際產出張數計費；可用畫質檔以目前金鑰的模型目錄為準。

請求契約

素材定位

每個 images[] 或 videos[] 項必須且只能提供以下一個欄位：

{ "url": "https://cdn.example.com/file.png" }

或：

{ "file_id": "vod-file-id" }

url 必須是公網可存取的絕對 http:// 或 https:// 位址。空字串、相對路徑、file://、ftp://、指向內網 / 迴環 / 鏈路本地的位址、帶認證資訊的 URL 以及同時提供兩個欄位都會在提交時同步拒絕。圖片介面、人臉辨識與數字人的 extra.sound_file 也遵循同一規則。

普通影片生成

普通影片使用 images[] 傳首尾幀或參考圖，使用 videos[] 傳一個參考 / 編輯影片。不要在頂層使用 OpenAI 的 image_url 或 video_url 欄位。

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> 和 <<<element_2>>> 在乾淨的攝影棚桌面上緩慢旋轉",
  "duration": 5,
  "resolution": "1080p",
  "audio": false,
  "images": [
    { "url": "https://cdn.example.com/first.png", "usage": "first_frame" },
    { "file_id": "vod-last-frame", "usage": "last_frame" },
    { "url": "https://cdn.example.com/reference-a.png", "usage": "reference" },
    { "file_id": "vod-reference-b", "usage": "reference" }
  ],
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ],
  "subjects": [
    { "id": "subject-92951593344", "name": "貓" },
    { "id": "subject-92951593345", "name": "狗" }
  ]
}

普通生成的 images[].usage 必填，可選 first_frame、last_frame、reference。首幀和尾幀各最多一張；指定尾幀必須同時提供首幀；參考圖超過兩張時不能再指定尾幀；kling-v2-1 同時提供首尾幀時 resolution 只能為 1080p。videos[] 最多一項，且 reference_type 必填。feature 僅 kling-v3-omni 和 kling-o1 開放；base 僅已實測且有價的 kling-v1-6 開放，必須是唯一素材，不能和圖片或主體混用。

騰訊還有兩條數量耦合限制：有參考影片時，reference 圖數 + 主體數最多 4；無參考影片時最多 7。沒有提示詞時必須至少有一個素材。省略 duration、resolution、audio 會統一歸一化為 5 秒、720P、無聲。

主體與分鏡

subjects[] 使用騰訊固定主體 ID，每項必須有非空 id，name 可選。只有 kling-v3-turbo、kling-v3、kling-v3-omni 支援主體。對 kling-v3，只要提供主體，騰訊 VOD 還要求 images[] 至少有一項且 usage: "reference"。主體按陣列位置綁定：subjects[0] 對應 <<<element_1>>>，subjects[1] 對應 <<<element_2>>>，依此類推。每個已提供主體都必須在 Prompt 中被引用；Prompt 也不能引用不存在的 <<<element_N>>>。

分鏡僅 kling-v3 和 kling-v3-omni 支援：

{
  "model": "kling-v3-omni",
  "prompt": "兩段式產品展示短片",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "盒子打開", "duration": 2 },
      { "index": 2, "prompt": "產品出現", "duration": 3 }
    ]
  }
}

mode 可取 intelligence 或 customize。智慧模式不能帶 segments，自訂模式必須帶分鏡。自訂分鏡從 1 開始連續編號，提示詞不能為空且不超過 512 字，每段至少 1 秒，時長總和必須嚴格等於總時長。請使用結構化 shots，extra.multi_shot、extra.shot_type、extra.multi_prompt 會被拒絕。

動作控制

動作控制必須提供恰好一個影片和一張人物圖，場景決定兩者含義，因此圖片不能帶 usage，影片不能帶 reference_type。videos[].keep_original_sound 是布林值，閘道會映射成騰訊 keep_original_sound 標記。目前唯一驗證過的額外參數是 extra.character_orientation（image 或 video）。動作控制時長由輸入影片決定，必須省略 duration，產物使用臨時儲存。

{
  "model": "kling-v3-motion-control",
  "prompt": "跟隨舞者的動作",
  "resolution": "1080p",
  "images": [{ "file_id": "vod-person-image" }],
  "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
  "extra": { "character_orientation": "video" }
}

數字人與對口型

數字人（kling-avatar）需要 1-5 張人物圖，不接受影片，並且必須在 extra.sound_file（HTTP(S) 音訊位址）和 extra.audio_id 中二選一。時長由輸入音訊決定，省略 duration。

對口型（kling-lip-sync）不接受圖片或影片。先用一個或多個素材呼叫人臉辨識：

curl https://api.hop-base.com/v1/kling/faces \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"file_id":"vod-source-video"}]}'

再提交返回的 session 和一個 face_choose 項：

{
  "model": "kling-lip-sync",
  "extra": {
    "session_id": "face-session-id",
    "face_choose": [
      { "face_id": "face-1", "sound_file": "https://cdn.example.com/voice.mp3" }
    ]
  }
}

face_choose 必須恰好一項，且包含非空 face_id 與 sound_file。輸入音訊 / 影片決定時長；對口型按秒計費並有 5 秒下限，4 秒成片按 5 秒收費。騰訊確認對應 SKU 前，voice_ids 和 extra.voice_list 均不可用。

提交與輪詢

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"紅球在白桌面上滾動","duration":5,"resolution":"720p"}'

202 回應會返回形如 kt57x<upstream-task-id> 的任務 ID。不要在查詢時傳計費標頭：

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

狀態為 queued、processing、completed 或 failed。完成後的 outputs 是 HopBase 中繼位址，插件不長期保存源檔；回源前會驗證任務級 file token。只有內部釘選輪詢觀察到騰訊成功 FINISH、ErrCode=0、產物合法且有計費時長時才產生一次 Usage。FINISH 但 ErrCode 或 ErrCodeExt 非空屬於失敗，不計費。

計費單位與桶

模型目錄中的 price.unit 明確單位：影片為 second，生圖為 image，人臉辨識為 call。影片基準價是騰訊人民幣牌價除以站內固定匯率 6.8；Core 再單獨乘分組倍率。

缺失或尚未確認的桶一律不可售，不會靜默落到相鄰價格。kling-v3-omni 4K 無聲 feature 參考影片桶等待第二份騰訊確認後再開放；呼叫方指定音色同樣暫不開放，請不要傳送 voice_ids 或 extra.voice_list。