Kling 3.0 マルチショット絵コンテ API ガイド

Q: kling-v3-turbo はマルチショットに対応していますか？

いいえ。kling-v3-turbo は主体には対応していますが、shots には対応していません。絵コンテには kling-v3 または kling-v3-omni を使ってください。

Q: 主体とカスタム絵コンテを組み合わせられますか？

はい。主体を subjects に入れ、トップレベルの prompt で >> として 1 回参照し、segments の各項目では "he" や "the man" のような平易な言葉でアクションを描写します。これでキャラクターはショット間で一貫します。kling-v3 では、主体を使う際に "usage": "reference" を指定した images[] の項目も 1 つ必要です。

Q: 絵コンテが "sum of shot durations must equal the total duration" で拒否されたのはなぜですか？

セグメントの長さの合計は、トップレベルの duration とちょうど一致しなければなりません。セグメントを書くときは必ず duration を明示的に指定し、デフォルト値に頼らないでください。

Q: Kling 本来の multi_shot や element_list パラメータは使えますか？

使えません。HopBase が受け付けるのは構造化された shots と subjects フィールドです。extra.multi_shot、extra.multi_prompt、extra.shot_type、extra.element_list をそのまま送ると、構造化フィールドを案内するメッセージとともに拒否されます。

Q: 何から始めればよいですか？

HopBase コンソールで Kling モデルを含むグループのキーを作成し、GET /v1/models で kling-v3 または kling-v3-omni があることを確認したうえで、上記の intelligence モードの例から始めてください。動画の中の動きを人物に真似させるという別の種類の制御については、Kling モーションコントロール API ガイドをご覧ください。

結論から言うと、Kling 3.0 は 1 本のクリップの中に複数のショットを描画でき、それをリクエスト内の構造化された shots オブジェクトで制御します。HopBase ではマルチショットは kling-v3 と kling-v3-omni で使え、どちらも 720p、1080p、2K、4K で 3〜15 秒のクリップを生成します。モードは 2 つあります。"mode": "intelligence" では、モデルがプロンプトを自動でショットに分割します。"mode": "customize" では、番号付きのセグメントを最大 6 つまで自分で記述します。各セグメントは最大 512 文字の独自プロンプトを持ち、長さは最低 1 秒で、セグメントの長さの合計はリクエストの duration とちょうど一致しなければなりません。すべてのショットで同じキャラクターを保つには、POST /v1/kling/subjects でカスタム主体（subject）を一度作成します（無料）。そのうえで subjects にその ID を渡し、プロンプト内では <<<element_1>>> として参照します。ショットや主体は秒単位の料金に影響しません。料金を左右するのは解像度、音声、参照動画だけです。

ショットと主体に対応する Kling モデル

モデル	尺	ショット（マルチショット）	主体	参照画像
`kling-v3-omni`	3〜15 秒	対応	対応	参照画像 + 主体 ≤ 7（参照動画ありの場合 ≤ 4）
`kling-v3`	3〜15 秒	対応	対応（ただし参照画像が 1 枚以上必要）	最大 6 枚
`kling-v3-turbo`	3〜15 秒	非対応	対応	非対応

旧世代の Kling モデル（o1、2.6、2.5 Turbo、2.1、1.6）はどちらにも対応していません。これらに shots を送ると model ... does not support shots (multi-shot storyboard) が返されます。お使いのキーで利用できるモデル ID は、必ず GET /v1/models で確認してください。

shots オブジェクト

リクエストはすべて POST https://api.hop-base.com/v1/video/generate に送ります。マルチショットでは shots フィールドを 1 つ追加し、次のルールに従います。

mode は intelligence または customize です。
intelligence モードでは segments を省略します。カットの位置はモデルが決めます。
customize モードでは segments が必須です。最大 6 つまでで、index は 1、2、3 … と欠番なく番号を振ります。
各セグメントの prompt は空にできず、最大 512 文字です。
各セグメントの duration は最低 1 秒で、長さの合計はトップレベルの duration とちょうど一致しなければなりません。セグメントを使うときは、必ず duration を明示的に指定してください。
構造化された shots オブジェクトを使ってください。Kling 本来の extra.multi_shot、extra.shot_type、extra.multi_prompt は拒否されます。

intelligence モード：カットはモデルに任せる

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 barista grinds coffee, pours latte art, then slides the cup across the counter to a smiling customer",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": { "mode": "intelligence" }
  }'

customize モード：絵コンテを自分で書く

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "A 10-second product story for a pair of trail running shoes",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": {
      "mode": "customize",
      "segments": [
        { "index": 1, "prompt": "Wide shot: a runner laces up the shoes at a misty trailhead at dawn", "duration": 3 },
        { "index": 2, "prompt": "Low tracking shot: the shoes hit wet rocks, water splashes in slow motion", "duration": 3 },
        { "index": 3, "prompt": "Close-up: the runner stops on a ridge, sunlight on the shoe logo", "duration": 4 }
      ]
    }
  }'

3 + 3 + 4 = 10 で、duration と一致しています。数値が一致しない場合、タスクが作成される前に sum of shot durations (9 s) must equal the total duration (10 s) でリクエストが拒否され、課金はされません。

カスタム主体でショット間のキャラクターを統一する

ストーリーの中でショットが切り替わるとき、難しいのは各ショットでキャラクターの見た目を揃えることです。Kling はこれを主体（subjects）で解決します。主体とは、参照メディアから一度作成し、以後は ID で再利用できる保存済みのキャラクターやオブジェクトです。

ステップ 1：主体を作成する（無料・非同期）

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Luna mascot",
    "description": "Orange fox mascot wearing a blue hoodie",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/luna-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/luna-side.png",
      "https://cdn.example.com/luna-back.png"
    ]
  }'

image_refer では、正面画像 1 枚と追加の参照画像 1〜3 枚が必要です。正面画像と同じ画像や、互いに重複する画像は使えません。
video_refer は代わりに 1 本の video_url から主体を作成し、オプションで voice_id を付けられます。1 回のリクエストで 2 つの方式を混在させることはできません。
name は最大 20 文字、description は最大 100 文字です。URL はすべて公開された http(s) アドレスでなければなりません。

呼び出すと 202 と id が返されます（object は kling.subject.task）。通常の動画タスクと同様に GET /v1/video/tasks/{task_id} でポーリングします。完了すると結果に element_ids が含まれ、それが主体の ID です。GET /v1/kling/subjects で作成済みの主体をすべて一覧できます。主体の作成は現在無料です。

ステップ 2：マルチショットのリクエストで主体を使う

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "Medium shot: <<<element_1>>> sits on a sofa holding a red gift box. Then a close-up: <<<element_1>>> lifts the lid and its eyes light up",
    "duration": 8,
    "resolution": "1080p",
    "subjects": [{ "id": "subject-92951593344", "name": "luna" }],
    "shots": { "mode": "intelligence" }
  }'

主体の参照の仕組みは次のとおりです。

主体は位置で対応付けられます。subjects[0] が <<<element_1>>>、subjects[1] が <<<element_2>>>、以下同様です。
送信したすべての主体は、トップレベルの prompt で参照されていなければなりません。そうでない場合は subjects[0] is not referenced in prompt as <<<element_1>>> が返されます。
送信していない主体を参照すること（たとえば 2 つしか送っていないのに <<<element_3>>> を使う）も拒否されます。
kling-v3 では、主体を含むリクエストに "usage": "reference" を指定した images[] の項目も 1 つ以上必要です。これがない場合、リクエストが Kling に届く前の送信時点で拒否されます。
例で intelligence モードを使っているのは、トップレベルのプロンプトがすべてのショットの台本になり、主体のトークンがモデルの読む位置に置かれるからです。主体は customize モードの segments とも併用できます。kling-v3-omni でのテストでは、トップレベルのプロンプトで <<<element_1>>> を 1 回参照し、各セグメントでは "the man" とだけ書きましたが、両方のショットに同じ主体が登場し、顔、眼鏡、白衣、赤いネクタイまで一致していました。参照はトップレベルの prompt に入れる必要があり、segments にだけ入れると送信時に subjects[0] is not referenced in prompt as <<<element_1>>> で拒否されます。ある比較実験では、すべてのセグメントで <<<element_1>>> を繰り返したところ、最初のショットにキャラクターが 2 人登場しました（1 人は歩いていて、もう 1 人はすでにベンチに座っている）。一方、セグメントに平易な説明だけを書いたバージョンではそうなりませんでした。主体はトップレベルで 1 回だけ参照し、各セグメントでは平易な言葉で描写し、規模を広げる前に 720p の短いテストを描画してください。

ポーリングと結果

これらはすべて非同期です。送信すると 202 と、kt57x… のようなタスク ID、および billing_bucket が返されます。status が completed または failed になるまで GET /v1/video/tasks/{task_id} をポーリングします。

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

完了したタスクには、完了から 24 時間有効な api.hop-base.com 上の署名付き URL である outputs と、billed_seconds と cost_usd（実際に差し引かれた金額）を含む usage が入ります。失敗したタスクには input_sensitive、invalid_request、generation_failed、timeout などの安定した error.code が入り、課金されることはありません。2 時間経っても完了しないタスクは自動的に失敗扱いになります。全フィールドのリファレンスは Kling 動画 API ドキュメントをご覧ください。

マルチショットの料金

Kling は出力の秒数に応じて課金され、単価はモデル、解像度、そしてクリップが無音か、音声付きか、参照動画を使うかで決まります。ショット、主体、参照画像によって料金が上がることはありません。モデルカードに記載された公式定価の例は次のとおりです。

モデル · 区分	720p	1080p	2K
`kling-v3` · 無音	$0.0882 / 秒	$0.1176 / 秒	$0.1471 / 秒
`kling-v3` · 音声付き	$0.1324 / 秒	$0.1765 / 秒	$0.2206 / 秒
`kling-v3-omni` · 無音、参照動画なし	$0.0882 / 秒	$0.1176 / 秒	$0.1471 / 秒
`kling-v3-omni` · 音声付き、参照動画なし	$0.1176 / 秒	$0.1471 / 秒	$0.1765 / 秒

つまり、上記の 10 秒の customize の例（kling-v3-omni、1080p、音声付き）は 10 × $0.1471 で、定価ベースで約 $1.47 です。4K の区分と参照動画ありの区分は kling-v3 と kling-v3-omni のモデルカードに記載しています。料金ページでは同じ区分を人民元（CNY）で掲載しており、たとえば kling-v3 1080p 音声付きは 1 秒あたり ¥1.20 です。実際の単価はご利用のグループによって異なります。

より良い絵コンテを作るコツ

各セグメントはショットリストの 1 行のように書く。まずフレーミング（"Wide shot"、"Close-up"、"Low tracking shot"）を書き、次にアクションを書きます。1 セグメントにつき 1 アクションが最も効果的です。
短いカットにも 2 秒以上を割り当てる。最低は 1 秒ですが、極端に短いセグメントでは動きの余地がほとんどありません。
まず intelligence モードの 720p で試作する。ストーリーが固まったら customize モードと高解像度に切り替えましょう。コストは秒数 × 解像度区分に比例します。
音声は必要なときだけオンにする。kling-v3 の 1080p では、音声をオンにすると単価が 1 秒あたり $0.1176 から $0.1765 に上がります。

よくある質問

Kling 3.0 の 1 本のクリップには何ショットまで入れられますか？

customize モードではカスタムセグメントを最大 6 つまで、クリップ全体の長さ 3〜15 秒の範囲で入れられます。intelligence モードではショット数をモデル自身が決めます。

kling-v3-turbo はマルチショットに対応していますか？

いいえ。kling-v3-turbo は主体には対応していますが、shots には対応していません。絵コンテには kling-v3 または kling-v3-omni を使ってください。

ショットや主体に追加料金はかかりますか？

かかりません。秒あたりの料金は、モデル、解像度、音声、参照動画の有無で決まります。カスタム主体の作成は現在無料です。

主体とカスタム絵コンテを組み合わせられますか？

はい。主体を subjects に入れ、トップレベルの prompt で <<<element_1>>> として 1 回参照し、segments の各項目では "he" や "the man" のような平易な言葉でアクションを描写します。これでキャラクターはショット間で一貫します。kling-v3 では、主体を使う際に "usage": "reference" を指定した images[] の項目も 1 つ必要です。

絵コンテが "sum of shot durations must equal the total duration" で拒否されたのはなぜですか？

セグメントの長さの合計は、トップレベルの duration とちょうど一致しなければなりません。セグメントを書くときは必ず duration を明示的に指定し、デフォルト値に頼らないでください。

Kling 本来の multi_shot や element_list パラメータは使えますか？

使えません。HopBase が受け付けるのは構造化された shots と subjects フィールドです。extra.multi_shot、extra.multi_prompt、extra.shot_type、extra.element_list をそのまま送ると、構造化フィールドを案内するメッセージとともに拒否されます。

何から始めればよいですか？

HopBase コンソールで Kling モデルを含むグループのキーを作成し、GET /v1/models で kling-v3 または kling-v3-omni があることを確認したうえで、上記の intelligence モードの例から始めてください。動画の中の動きを人物に真似させるという別の種類の制御については、Kling モーションコントロール API ガイドをご覧ください。