カスタムサブジェクトを作成

画像または動画 1 本から Kling のカスタムサブジェクトを作成します。得られたサブジェクト ID は動画リクエストの `subjects[].id` に指定します。

POST/v1/kling/subjects

image_refer には正面画像 1 枚と補助参照画像 1–3 枚が必要です。video_refer には動画 1 本が必要で、voice_id を任意で紐付けられます。2 つの方式のフィールドは混在できません。アドレスはすべて公開された 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 は動画 1 本から作成

取りうる値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 が不正、表にないフィールドがある、またはリクエストボディの後ろに 2 つ目の 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

レスポンス

エラー

関連ページ