Skip to content
NEWNano Banana 2.1 が登場 — Google の最新画像生成モデル、1 枚 $0.0336 から、ネイティブ 4K、前世代の約半額モデルを見る
HopBase
← ブログに戻る

Kling モーションコントロール API ガイド（v3・v2.6）

HopBase 2026年10月29日 21 分で読めます

結論から言うと、Kling のモーションコントロールは、人物画像 1 枚とモーション動画 1 本を受け取り、画像の人物に動画の動きを演じさせる機能です。HopBase では、モデル kling-v3-motion-control（720p、1080p、2K、4K）または kling-v2-6-motion-control（720p、1080p）で呼び出せます。どちらも他の Kling モデルと同じ非同期エンドポイントを使います：POST https://api.hop-base.com/v1/video/generate で送信し、GET /v1/video/tasks/{task_id} をポーリングします。画像と動画はちょうど 1 つずつ送り、duration は指定しないでください。出力の長さはモーション動画の長さと同じになるためです。追加のパラメータは extra.character_orientation（image または video）だけです。課金は出力動画の秒数単位で、失敗したタスクは無料、結果のリンクは 24 時間有効です。最も失敗しやすいのはモーション動画そのものです。実在の人物の上半身全体（頭から腰まで）が映っている必要があります。

モーションコントロールとは何か、アバターやリップシンクではなくこれを使うべき場面

Kling には人物を動かすワークフローが 3 つあり、それぞれ別の目的に対応しています：

モデル入力動く部分出力の長さ
kling-v3-motion-control / kling-v2-6-motion-control人物画像 1 枚 + モーション動画 1 本全身が動画の動きをなぞるモーション動画と同じ
kling-avatar人物画像 1～5 枚 + 音声トラック 1 本顔と口が音声に合わせて動く音声と同じ
kling-lip-sync既存の動画 + 新しい音声口だけを新しい音声に合わせて再同期元の動画と同じ

モーションコントロールが適しているのは、手元に動き（ダンス、商品デモの身振り、歩行サイクル、プレゼンターの身振り手振り）があり、それを別のキャラクター——ブランドのマスコット、新しい衣装を着たモデル、生成したペルソナなど——に演じさせたい場合です。キャラクターに話させるだけならアバターかリップシンクを使ってください。両方とも Kling デジタルヒューマンガイドで解説しています。

v3 か v2.6 か：解像度と定価

どちらのモデルも、指定した解像度の料金で出力 1 秒ごとに課金されます。以下は各モデルカードに掲載されている公式定価です（実際の料金はご利用のグループによって異なり、ログイン後のモデルカタログに表示されます）：

モデル720p1080p2K4K
kling-v3-motion-control$0.1324 / s$0.1765 / s$0.2647 / s$0.3971 / s
kling-v2-6-motion-control$0.0735 / s$0.1176 / s——

計算例として、kling-v3-motion-control で 10 秒の 1080p クリップを生成すると、定価で 10 × $0.1765 = 約 $1.77 です。料金ページでは同じ 1080p の料金が CNY 建て（1 秒あたり ¥1.20）で表示されています。下書きや大量の 720p 生成には v2.6、2K や 4K が必要な場合は v3 を使いましょう。各料金帯の価格は kling-v3-motion-control と kling-v2-6-motion-control のモデルカードに記載しています。

ステップ 1：タスクを送信する

リクエストの送信先は、他のすべての Kling 動画と同じエンドポイントです。各入力の役割はシーンによって決まるため、画像には usage フィールドを、動画には reference_type を指定しません：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "prompt": "Copy the dance moves from the video",
    "resolution": "1080p",
    "images": [{ "url": "https://cdn.example.com/character.png" }],
    "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
    "extra": { "character_orientation": "video" }
  }'

フィールドごとの説明：

  • images：ちょうど 1 件。動きを演じる人物です。
  • videos：ちょうど 1 件。動きの元になる動画です。keep_original_sound: true で元動画の音声トラックを残します。モーションコントロールは新しい音声を一切生成しません。
  • extra.character_orientation：任意で、image または video。2 つの値の主な違いは、カメラの挙動と入力の長さです。同じ人物画像と、180° のターンを含む同じモーションクリップでテストしたところ、どちらのモードでもキャラクターは振り向いて背中を見せました。image は人物画像の構図とカメラ位置を維持し、背景はほぼ静止したままで、最長 10 秒のモーション動画を受け付けます。video はモーション動画に合わせてカメラがフレーミングを変えたり移動したりし、最長 30 秒のモーション動画を受け付けます。省略した場合、HopBase は video を送信します。モーションコントロールで受け付ける extra キーはこれだけで、それ以外のキーは 400 を返します。
  • resolution：v3 では 720p / 1080p / 2k / 4k、v2.6 では 720p / 1080p。課金の料金帯もこれで決まります。
  • duration：送信しないでください。長さは入力動画から決まり、送信すると duration of model ... is determined by the input media; do not pass duration が返されます。

各メディア項目には url か file_id のどちらか一方だけを指定します。url は絶対パスで、公開アクセス可能な http(s) アドレスでなければなりません。相対パス、file://、プライベート IP やループバック IP、認証情報を埋め込んだ URL は送信時に拒否されます。送信に成功すると、kt57x… のようなタスク ID とともに 202 が返されます。

ステップ 2：タスクが終わるまでポーリングする

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

ステータスは queued から processing へ進み、completed または failed で終わります。終了状態はこの 2 つだけなので、それ以外はすべて実行中として扱ってください。完了したタスクは次のようになります：

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "...", "billed_seconds": 10, "cost": 12.0, "cost_usd": 1.765, "currency": "CNY" }
}

outputs は api.hop-base.com 上の署名付きリンクで、完了から 24 時間有効です。再度ポーリングしても期限は延長されないため、すぐに自社のストレージへダウンロードしてください。usage.cost_usd は、このタスクで実際に差し引かれた金額です。最小限の Python ループ：

import time, requests

API = "https://api.hop-base.com/v1"
H = {"Authorization": "Bearer sk-YOUR_KEY"}

task = requests.post(f"{API}/video/generate", headers=H, json={
    "model": "kling-v3-motion-control",
    "prompt": "Copy the dance moves from the video",
    "resolution": "1080p",
    "images": [{"url": "https://cdn.example.com/character.png"}],
    "videos": [{"url": "https://cdn.example.com/dance.mp4"}],
    "extra": {"character_orientation": "video"},
}).json()

while True:
    t = requests.get(f"{API}/video/tasks/{task['id']}", headers=H).json()
    if t["status"] == "completed":
        print(t["outputs"][0]); break
    if t["status"] == "failed":
        raise RuntimeError(f"{t['error'].get('code')}: {t['error']['message']}")
    time.sleep(5)

Kling のリクエスト仕様には Webhook フィールドがないため、タスクの追跡はポーリングでのみ行えます。作成から 2 時間経っても終わらないタスクは、error.code timeout で失敗扱いとなり、課金されません。タスクはキャンセルできません。

モーション動画：最も失敗しやすいステップ

HopBase は送信時にリクエストの構造（件数、フィールド名、URL の形式、解像度）をチェックします。メディアそのもの（形式、サイズ、解像度、長さ、内容）をチェックするのは Kling で、タスクの実行中に行われます。要件を満たさない動画はいったん受け付けられ、数分後に失敗します。モーションコントロールで最も多いケース：

error.code: reference_input_invalid
the motion reference video was rejected: no complete human upper body was detected in it;
use a video in which a real person's upper body (head to waist) is clearly visible, then submit again

モーション動画の実践的なルール：

  • 実在の人物を使ってください。動物、クリーチャー、人間以外のキャラクターは拒否されます。
  • クリップ全体を通して、頭から腰までがフレーム内に収まり、遮られていない状態を保ってください。寄りすぎたクロップ、胴体の前にあるテーブルや小道具、強いモーションブラーはいずれも問題の原因になります。
  • データセンターのクライアントに安定してファイルを配信できる場所にホストしてください。サーバー IP をブロックする無料のファイルホスティングより、自社のオブジェクトストレージや CDN のほうが安全です。
  • クリップの長さがそのまま出力の長さになり、コストも決まることを忘れないでください。送信前に動画をトリミングしましょう。
  • 長さの上限に注意してください：モーション動画は character_orientation: image では最長 10 秒、video（デフォルト）では最長 30 秒です。これより長いクリップは送信から約 30 秒後に error.code invalid_request で失敗し、課金されません。テストでは、12 秒のクリップは image モードで拒否され、video モードでは 12 秒の結果がそのまま生成されました。31 秒のクリップは video モードでも拒否されました。
  • 出力のアスペクト比はモーション動画ではなく人物画像に従います。9:16 の縦長モーション動画と約 5:6 の人物画像を組み合わせると 864×1040 の結果になったため、縦長の出力が欲しい場合は縦長の人物画像を使ってください。image モードでは出力がクリップよりわずかに短くなることがあります。5 秒のクリップから 4.8 秒の動画が生成され、4 秒分として課金されました。

失敗したタスクは一切課金されないため、動画が拒否されても失うのは時間だけです。

送信時のエラー

送信時のエラーではタスクは作成されず、費用もかかりません。モーションコントロール特有のエラーと、その正確なメッセージ：

送信した内容error.message
画像が 0 枚または 2 枚、あるいは動画がないmotion control requires exactly 1 motion video and 1 character image
画像に usage を指定motion control images[0] does not accept usage; the character image role is fixed by the scene
動画に reference_type を指定motion control videos[0] does not accept reference_type; the motion video role is fixed by the scene
image/video 以外の orientation の値extra.character_orientation must be image or video
durationduration of model kling-v3-motion-control is determined by the input media; do not pass duration
size など OpenAI の API のフィールドrequest body does not match the JSON contract: json: unknown field "size"

code insufficient_balance の 402 は、利用可能残高から実行中タスクの見積もりコストを差し引いた額では、このタスクをまかなえないことを意味します。この確保分はタスクが終了すると解放されます。エラーの一覧は Kling 動画 API ドキュメントにあります。

パイプラインに組み込む

典型的な本番構成では、商品の披露、あいさつ、ダンスの一拍など、動きごとにきれいなモーションクリップを 1 本ずつ撮影します。そのクリップを、さまざまなモデル、衣装、ブランドキャラクターといった多数の人物画像に対して実行します。1 回あたりのコストはクリップの長さ × 秒単価なので、費用を予測しやすくなります。同じ API キーで、Kling のテキストから動画生成、ナレーション用の MiniMax 音声合成、プロンプトを書くためのチャットモデルも、キーのグループにそれらのモデルが含まれていれば利用できます。キーで利用できるモデルは GET /v1/models で確認してください。

よくある質問

モーションコントロール動画の長さは指定できますか？

できません。duration は省略する必要があり、送信すると 400 が返されます。出力の長さは指定したモーション動画と同じなので、長さとコストは元のクリップをトリミングして調整してください。

モーション動画はどれくらいの長さまで使えますか？

extra.character_orientation によって異なります：image では最長 10 秒、video（デフォルト）では最長 30 秒です。これより長いクリップはタスク開始から約 30 秒後に invalid_request で失敗し、課金されません。より長い結果が必要な場合は、動きを複数のクリップに分けてそれぞれ生成し、つなぎ合わせてください。

character_orientation は image と video のどちらを使うべきですか？

どちらのモードでも、キャラクターはモーション動画内のターンに追従します。固定アングルの商品ショットのように、人物画像のカメラ位置と構図を維持したい場合は image を使い、クリップは 10 秒以内に収めてください。カメラの動きもなぞりたい場合や、クリップが 10 秒を超える場合は video を使います。

モーションコントロールは音声を生成しますか？

新しい音声は生成されません。モーション動画のサウンドトラックを残すには、videos[0].keep_original_sound を true に設定してください。extra.keep_original_sound は拒否されるため、extra には入れないでください。

受け付けられたタスクが数分後に失敗したのはなぜですか？

Kling は送信時ではなくタスクの実行中にメディアを検証します。最も多い原因は、実在の人物の上半身がはっきり映っていないモーション動画です（reference_input_invalid）。そのほか、読み込めない URL やコンテンツ審査（input_sensitive）も原因になります。失敗したタスクは課金されません。

kling-v3-motion-control と kling-v2-6-motion-control の違いは何ですか？

v3 は 720p、1080p、2K、4K に対応しています。v2.6 は 720p と 1080p に対応し、秒あたりの定価が低くなっています（720p で $0.0735 / s、1080p で $0.1176 / s。v3 は $0.1324 / s と $0.1765 / s）。リクエスト形式はどちらも同じです。

結果はいつまでダウンロードできますか？

タスクが完了した時点から 24 時間です。再度ポーリングしても同じリンクが返されるだけで期限は延長されず、期限切れのリンクは 410 を返します。

利用を始めるにはどうすればよいですか？

HopBase コンソールで、Kling モデルを含むグループを付けた API キーを作成します。その後 GET /v1/models を実行し、kling-v3-motion-control が表示されることを確認してください。定価は料金ページをご覧ください。

チュートリアルKling動画生成