建立自訂主體

用圖片或一段影片建立可靈自訂主體，得到的主體 ID 填入影片請求的 `subjects[].id`。

POST/v1/kling/subjects

image_refer 需要一張正面圖加 1–3 張輔助參考圖；video_refer 需要一段影片，可選繫結 voice_id。兩種方式的欄位不能混用。所有位址都必須是公網 HTTP(S) 絕對位址，規則同素材定位。

建立是非同步任務，目前不計費。提交回傳 202 與任務 id（object 為 kling.subject.task），用查詢影片任務輪詢；完成後結果裡帶 element_ids（主體 ID 陣列）與 elements（每項含 id，可能帶 info）。

請求體是嚴格 JSON 格式：表外欄位在任務建立前回傳 400。欄位校驗全部在提交前完成，不合規不會建立任務。

建立自訂主體

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "橘貓",
    "description": "短毛橘貓，綠色眼睛",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/cat-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/cat-side.png",
      "https://cdn.example.com/cat-back.png"
    ]
  }'

202application/json

{
  "id": "ktEXAMPLE",
  "object": "kling.subject.task",
  "status": "queued",
  "created": 1790000000
}

請求標頭

Authorization:必填string

Bearer sk-…：主控台「API 金鑰」中建立的金鑰，所屬分組須包含請求的模型

請求主體參數JSON

name:必填string

主體名稱，前後空白會被去掉

長度1–20 字元

description:選填string

主體描述

長度≤ 100 字元

reference_type:必填string

image_refer 用圖片建立，video_refer 用一段影片建立

可選值image_refervideo_refer

frontal_image_url:選填string

正面圖位址；image_refer 必填，video_refer 不能帶，必須是公網可存取的絕對 HTTP(S) 位址

長度≥ 1 字元

reference_image_urls:選填array of string

輔助參考圖位址；image_refer 必填，1–3 個，不能與正面圖重複、彼此也不能重複；video_refer 不能帶

數量1–3 項

video_url:選填string

影片位址；video_refer 必填，image_refer 不能帶，必須是公網可存取的絕對 HTTP(S) 位址

長度≥ 1 字元

voice_id:選填string

繫結到主體的音色，僅 video_refer 可用

tag_ids:選填array of string

用於歸類主體的標籤 ID，每項非空且不重複

回傳

202已受理，回傳主體建立任務

id:選填string

任務 ID，用 GET /v1/video/tasks/{task_id} 輪詢

object:選填string

固定為 kling.subject.task

status:選填string

固定為 queued

created:選填integer

建立時間，Unix 秒

錯誤

400提交前校驗失敗，不建立任務。原文如： request body does not match the JSON contract: …：JSON 不合法、帶了表外欄位或請求體後面還有第二個 JSON 值 name is required、name cannot exceed 20 characters、description cannot exceed 100 characters reference_type must be image_refer or video_refer reference_type=image_refer does not accept video_url、voice_id is only supported with reference_type=video_refer、reference_type=video_refer does not accept image references reference_image_urls must contain 1 to 3 reference images different from the frontal image、reference_image_urls[<序號>] duplicates the frontal image or another reference image <欄位> is required、<欄位>.url must be a publicly accessible absolute http(s) URL tag_ids[<序號>] cannot be empty、tag_ids[<序號>] is duplicated

401沒帶金鑰、金鑰無效或已過期（missing_api_key / invalid_api_key / api_key_expired）

請求標頭

請求主體參數JSON

回傳

錯誤

相關頁面