Kling(可灵)動画・画像 API

HopBase 上の Kling は非同期 API です。まずタスクを送信し、その後 HopBase のタスク ID をポーリングします。Kling のプランに属するキーを使用し、課金対象の処理を送信する前に GET /v1/models で正確なモデル ID を確認してください。

エンドポイント

すべてのリクエストは Authorization: Bearer sk-your-key と Content-Type: application/json を使用します。ボディは厳格にデコードされます。未知のフィールド、2 つ目の JSON 値、トップレベルの image_url / video_url、検証されていないネストされたフィールドは、リクエストが送信される前に拒否されます。

モデル一覧

Kling の画像モデル 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:// の URL である必要があります。空文字列、相対パス、file://、ftp://、プライベート / ループバック / リンクローカルアドレス、認証情報を含む URL、および両方のフィールドを同時に指定した場合は、送信時に同期的に拒否されます。同じルールが画像用エンドポイント、顔検出、アバターの extra.sound_file にも適用されます。

通常の動画生成

フレームや参照画像には images[] を、参照 / 編集用の動画 1 本には videos[] を使用します。トップレベルで OpenAI の image_url や video_url フィールドを使用しないでください。

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> and <<<element_2>>> rotate slowly on a clean studio table",
  "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": "cat" },
    { "id": "subject-92951593345", "name": "dog" }
  ]
}

通常生成では images[].usage が必須で、first_frame、last_frame、reference のいずれかを指定します。先頭フレームと末尾フレームはそれぞれ最大 1 枚まで指定でき、末尾フレームを指定する場合は先頭フレームも必要です。reference 画像が 2 枚を超える場合、末尾フレームは指定できません。kling-v2-1 で先頭フレームと末尾フレームの両方を指定すると、resolution は 1080p に限定されます。videos[] は最大 1 件で、reference_type は必須です。feature 動画は kling-v3-omni と kling-o1 のみが受け付けます。base 動画は kling-v1-6 のみが受け付け、それが唯一のメディア入力である必要があり、画像やサブジェクトと組み合わせることはできません。

Kling には数量に関する連動制限もあります。参照動画がある場合、reference 画像の枚数とサブジェクトの数の合計は最大 4 です。参照動画がない場合は最大 7 です。空のプロンプトは、メディア入力がリクエストに含まれている場合にのみ許可されます。duration、resolution、audio を省略すると、それぞれ 5 秒、720P、無音に正規化されます。

サブジェクトとショット

subjects[] は固定のサブジェクト ID を使用します。各要素には空でない id が必須で、name は任意です。サブジェクトは kling-v3-turbo、kling-v3、kling-v3-omni のみでサポートされます。kling-v3 では、サブジェクトが存在する場合、Kling は images[] に usage: "reference" の要素が少なくとも 1 つあることも要求します。要素は位置で対応し、subjects[0] が <<<element_1>>>、subjects[1] が <<<element_2>>> というように続きます。指定したすべてのサブジェクトはプロンプト内で参照される必要があり、逆に存在しないサブジェクトに対する <<<element_N>>> をプロンプトで参照することはできません。

ショットは kling-v3 と kling-v3-omni のみでサポートされます。

{
  "model": "kling-v3-omni",
  "prompt": "A short product story in two shots",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "The box opens", "duration": 2 },
      { "index": 2, "prompt": "The product is revealed", "duration": 3 }
    ]
  }
}

mode は intelligence または customize です。intelligence モードでは segments を省略する必要があり、customize モードでは必須です。カスタムセグメントは 1 から連番で振られ、512 文字以内の空でないプロンプトを持ち、それぞれ最低 1 秒以上で、長さの合計はリクエストの duration と厳密に一致する必要があります。構造化された shots を使用してください。生の extra.multi_shot、extra.shot_type、extra.multi_prompt は拒否されます。

モーションコントロール

モーションコントロールのタスクには、動画 1 本と人物画像 1 枚がちょうど必要です。意味はシーンによって決まるため、画像には usage を、動画には reference_type を指定しないでください。videos[].keep_original_sound は真偽値で、Kling の keep_original_sound フラグに対応します。現時点で検証済みの追加パラメータは extra.character_orientation(image または video)のみです。モーションコントロールの長さは入力動画によって決まるため duration は省略する必要があり、出力は一時的なものです。

{
  "model": "kling-v3-motion-control",
  "prompt": "Follow the dancer's movement",
  "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) の音声 URL)と extra.audio_id のどちらか一方が必須です。長さは入力音声から決まるため、duration は省略してください。

リップシンク(kling-lip-sync)は画像も動画も受け付けません。まず 1 つ以上のメディアロケーターを指定して顔検出を呼び出します。

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

続いて、返された session に対して face_choose を 1 件だけ指定して送信します。

{
  "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 を持つ要素をちょうど 1 件含む必要があります。長さは入力の音声 / 動画によって決まります。対応する Kling の機能が確認できるまで、生の extra.voice_list と voice_ids は意図的に利用できないようになっています。

送信とポーリング

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":"A red ball rolls across a white table","duration":5,"resolution":"720p"}'

送信に成功すると 202 が返り、タスク ID は id に kt57x<task-id> のような形式で入っています。Kling の画像生成(POST /v1/images/generations)も同様に非同期で、同じ形式の id とともに 202 を返します。どちらのタスクも、課金用のヘッダーを付けずに同じ方法でポーリングします。

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

status は queued → processing → completed または failed と遷移し、終了状態はこの最後の 2 つのみです。それ以外の値は実行中として扱ってください。完了したタスクには、api.hop-base.com ドメインから配信される署名付き URL が outputs に入っており、タスク完了時点から 6 時間有効です。再度照会しても同じ URL が返るだけで有効期限は延長されず、期限切れのリンクは 410 を返すため、この時間内に結果をダウンロードしてください。正常に完了したタスクのみが課金され、失敗したタスクは課金されません。

料金

Kling は動画生成について、video token ではなく、モデルの解像度と無音 / 音声あり / 参照動画の有無のティアに応じたレートで、出力動画の秒数単位で課金します。公式のリスト価格は料金ページに掲載されています。実際の適用レートはログイン後のモデルカタログに表示され、各リクエストの実際の課金額は利用量レコードで確認できます。