Kling 2.6 Motion Control
1 枚の画像のキャラクターに、3~30 秒の動画 1 本の動きを再現させます。720p または 1080p に対応し、結果の長さは画像の向きなら最大 10 秒、動画の向きなら最大 30 秒です。
- 非同期です。作成の呼び出しはタスク ID を返し、動画はタスクが成功した時点で得られます。
- 入力は 2 つで、どちらも必須です。キャラクター画像 1 枚と、3~30 秒のモーション動画 1 本です。画像のキャラクターが動画の動きを演じます。
character_orientationは、キャラクターの向きが何に従うかと、結果の最大の長さを決めます。image(デフォルト)なら最大 10 秒、videoなら最大 30 秒です。durationフィールドはありません。結果はモーション動画と同じ長さで、選んだ向きの上限までです。- 料金は、完成した動画の秒数に応じて、720p または 1080p の単価で決まり、作成時に確保した金額から精算されます。失敗したタスクには課金されません。
執筆時点で、Kling のモーションコントロールモデルはどちらも、公開中の GET /v1/media/models の一覧に載っていません。モデルが一覧にない間は、そのモデルのタスク作成に 503 processing_unavailable が返り、課金されません。利用を前提に組み込む前に、一覧を確認してください。
このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。
モデル ID
2 つのモデルがこのエンドポイントと同じ入力を共有します。以下の値はゲートウェイの仕様から直接取得したものです。background_source を受け付けるのは Kling 3.0 Motion Control のみです。
エンドポイントと認証
POST https://api.beatapi.io/v1/videos/tasks
Authorization
string
必須
BeatAPI の API キーを Bearer <BEATAPI_API_KEY> の形式で送信します。キーはダッシュボードで作成できます。キーはサーバー側で保管し、ブラウザーやモバイルアプリに含めないでください。
ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。
リクエストの流れ
タスクを作成する
下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。
完了を待つ
GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds(画像は 5 秒、動画は 8 秒)だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。
入力モード
リクエストパラメーター
model
string
必須
実行するモデルです。
値:kling-2.6-motion-control
値が正しくない場合
- 指定がない場合:
"model" is required - 画像モデルをこのエンドポイントに送った場合:
"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
prompt
string
任意
キャラクターやシーンについての任意のテキスト指示です。動き自体は動画から取られます。
長さ:≤ 2500 文字
- 長さは文字数で数えます(CJK 文字は 1 文字として数えます)。空文字列も受け付けます。
値が正しくない場合
- 上限を超えている場合:
"prompt" has an unsupported length
images
string[]
必須
キャラクター画像で、リンクはちょうど 1 個です。動きを演じる対象になります。
要素数:1–1
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 公開 HTTPS リンク 1 個のリストを送ります。ローカルファイルは
POST /v1/filesでアップロードし、返されたdata.urlをここで使えます。 - タスク作成時に、画像のサイズ、形式、寸法は確認されません。
値が正しくない場合
- 指定がない場合:
"images" is required - 空のリスト:
"images" requires at least 1 item - リンクが 2 個以上:
"images" accepts at most 1 items - https:// のリンクではない場合:
"images[0]" must be a public HTTPS URL
reference_videos
string[]
必須
モーション動画で、リンクはちょうど 1 個です。images のキャラクターが、この動画の動きを再現します。
要素数:1–1
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 長さは 3~30 秒である必要があります(「入力メディアの上限」を参照)。結果はこの動画と同じ長さで、
character_orientationが定める上限までです。 - ホストが許可している場合、ゲートウェイはタスク作成前にバイトレンジリクエストでファイルヘッダーから長さを読み取ります。
- ローカルファイルは
POST /v1/filesでアップロードし(動画は最大 100 MB)、返されたdata.urlをここで使えます。
生成された動画の秒数に応じて課金されるため、必要な動きだけにクリップを切り詰めてください。character_orientation: "image" の場合、結果は最大 10 秒です。
値が正しくない場合
- 指定がない場合:
"reference_videos" is required - 空のリスト:
"reference_videos" requires at least 1 item - リンクが 2 個以上:
"reference_videos" accepts at most 1 items - https:// のリンクではない場合:
"reference_videos[0]" must be a public HTTPS URL - 3 秒未満、または 30 秒を超える場合:
reference_videos[0] is 2 seconds long; this model takes reference video of 3 to 30 seconds. - ホストがエラーまたは空のファイルを返す場合:
reference_videos[0] could not be downloaded: the URL returned HTTP 404.
resolution
string
任意デフォルト: 720p
出力解像度です。料金区分も兼ねており、1080p は 720p より 1 秒あたりの料金が高くなります。
指定できる値:720p, 1080p
デフォルト:720p
- 小文字のみです。省略すると
720pが使われます。
値が正しくない場合
- リストにない値(例:
480p、4k、1080P):"resolution" must be one of: [720p 1080p]
character_orientation
string
任意デフォルト: image
キャラクターの向きを、キャラクター画像(image)とモーション動画(video)のどちらに合わせるかを指定します。
指定できる値:image, video
デフォルト:image
- 結果の最大の長さも決まります。
imageなら最大 10 秒、videoなら最大 30 秒です(「向きと長さの関係」を参照)。 - 省略すると
imageが使われるため、10 秒を超えるモーション動画にはvideoを明示する必要があります。 - タスク作成時に残高から確保される金額も決まります。その向きで許される最長の結果の分です(「課金」を参照)。
値が正しくない場合
- リストにない値:
"character_orientation" must be one of: [image video]
ゲートウェイはタスク作成前に、次の組み合わせも確認します。
- キャラクター画像 1 枚と、アップロード済みの 3~30 秒の動作動画 1 本が必要です。
character_orientation: imageの場合、出力は最大 10 秒です。
入力メディアの上限
ゲートウェイはタスク作成前にすべての入力を読み取り、次の上限を超えるものは、その入力を示す 400 bad_request で拒否します。課金はされません。
- タスク作成時に長さの上限が確認されるのはモーション動画だけです。3~30 秒で、ファイルヘッダーから測定し、許容差は 0.1 秒です。メッセージでは、フィールドのエラーと同様に 0 から数えた位置で入力を示します:
reference_videos[0] is 45 seconds long; this model takes reference video of 3 to 30 seconds. - 長さを読み取れないクリップ(ホストがバイトレンジリクエストを許可していない、またはファイルが MP4 や MOV ではない場合)は、この段階では拒否されず、計測もされません。作成の呼び出しが拒否されるのは、ホストがエラーまたは空のファイルを返した場合のみです。例:
reference_videos[0] could not be downloaded: the URL returned HTTP 404. imageは 10 秒までのクリップに使ってください。10 秒を超えるモーション動画には、character_orientation: "video"を送ってください。- タスク作成時に、画像のサイズ、形式、寸法は確認されません。
- ローカルファイルがある場合は、
POST /v1/filesでアップロードし(png、jpg、jpeg、webp の画像は最大 50 MB、mp4 または mov の動画は最大 100 MB)、返されたdata.urlを渡してください。
向きと長さの関係
duration フィールドはありません。結果はモーション動画と同じ長さで、character_orientation が上限を決めます。
- タスク終了時に、生成された動画について報告された使用量から精算されます。通常は、その長さに 1 秒あたりの定価を掛けた金額です。確保額との差額は返金されます。使用量が報告されない場合は、確保額が課金されます。「課金」を参照してください。
このモデルが受け付けないフィールド
以下のフィールドを送ると、無視されるのではなく、課金前に拒否されます。
duration、aspect_ratio、generate_audio、seed、task_type、output_format、reference_images、reference_audios、quality、sound、watermark、およびほかの動画モデルのフィールド →field "duration" is not supported by model kling-2.6-motion-control(送ったフィールド名が入ります)。background_source→field "background_source" is not supported by model kling-2.6-motion-control。受け付けるのはkling-3-motion-controlのみです。- API がまったく認識しないフィールド →
unknown field: <name>。
リクエスト例
モーション転送
動画リンクは、ご自身の 3~30 秒の MP4 または MOV に置き換えてください(公開のサンプル動画はありません)。character_orientation は省略しているため image が適用され、結果は最大 10 秒です。
1080p、向きは動画に従う
10 秒を超えるクリップ向けです。video なら最大 30 秒の結果になります。動画リンクは、ご自身のクリップに置き換えてください。結果が長いほど、タスク作成時に残高から確保される金額が増えます。
レスポンス
タスクの作成(201)
タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。
完了したタスク
GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。
出力フィールド
失敗したタスク
失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。
完全なコード例
タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。
課金
- これらの料金はモデルが一覧に載った後に適用されます。それまでは作成リクエストは拒否され、課金されません。
- 料金は、完成した動画の秒数に応じて、
resolutionごとの単価で決まります。character_orientationとプロンプトは単価に影響しません。下の表は 8 秒の結果の料金です。 - 結果はモーション動画と同じ長さになるため、タスク作成時には最終的な料金が決まっていません。ゲートウェイは、その解像度の単価で、向きが許す最長の結果分を確保します。
imageなら 10 秒、videoなら 30 秒です。目安は、imageで 1.00(1080p)、videoで 3.00(1080p)です。残高がこの金額を満たしていない場合、作成の呼び出しは402 insufficient_creditsで失敗します。 - タスクが終了すると、生成された動画について報告された使用量から精算されます。通常は、その長さに 1 秒あたりの定価を掛けた金額です。確保額の残りは返金されます。使用量が報告されない場合は、確保額が課金されます。課金された金額は
usage.credits_chargedとusage.credits_settledに表示されます。このモデルのusage.billable_duration_secondsは、作成時に確保した秒数(10 または 30)を示し、完成した動画の長さではありません。支払った金額は credits のフィールドで確認してください。 - 失敗したタスク(送信後にモデレーションで拒否されたものを含む)は全額返金されます。タスクが作成される前に拒否されたリクエストには課金されません。
現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。
よくあるエラー
HTTP エラー早見表
タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。
2 つのモデルの違い
認証
API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。
ヘッダー
ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。
リクエスト
キャラクター画像で、リンクはちょうど 1 個です。動きを演じる対象になります。
要素数:1–1
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 公開 HTTPS リンク 1 個のリストを送ります。ローカルファイルは
POST /v1/filesでアップロードし、返されたdata.urlをここで使えます。 - タスク作成時に、画像のサイズ、形式、寸法は確認されません。
値が正しくない場合
- 指定がない場合:
"images" is required - 空のリスト:
"images" requires at least 1 item - リンクが 2 個以上:
"images" accepts at most 1 items - https:// のリンクではない場合:
"images[0]" must be a public HTTPS URL
実行するモデルです。
値:kling-2.6-motion-control
値が正しくない場合
- 指定がない場合:
"model" is required - 画像モデルをこのエンドポイントに送った場合:
"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
モーション動画で、リンクはちょうど 1 個です。images のキャラクターが、この動画の動きを再現します。
要素数:1–1
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 長さは 3~30 秒である必要があります(「入力メディアの上限」を参照)。結果はこの動画と同じ長さで、
character_orientationが定める上限までです。 - ホストが許可している場合、ゲートウェイはタスク作成前にバイトレンジリクエストでファイルヘッダーから長さを読み取ります。
- ローカルファイルは
POST /v1/filesでアップロードし(動画は最大 100 MB)、返されたdata.urlをここで使えます。
備考:生成された動画の秒数に応じて課金されるため、必要な動きだけにクリップを切り詰めてください。character_orientation: "image" の場合、結果は最大 10 秒です。
値が正しくない場合
- 指定がない場合:
"reference_videos" is required - 空のリスト:
"reference_videos" requires at least 1 item - リンクが 2 個以上:
"reference_videos" accepts at most 1 items - https:// のリンクではない場合:
"reference_videos[0]" must be a public HTTPS URL - 3 秒未満、または 30 秒を超える場合:
reference_videos[0] is 2 seconds long; this model takes reference video of 3 to 30 seconds. - ホストがエラーまたは空のファイルを返す場合:
reference_videos[0] could not be downloaded: the URL returned HTTP 404.
キャラクターの向きを、キャラクター画像(image)とモーション動画(video)のどちらに合わせるかを指定します。
指定できる値:image, video
デフォルト:image
- 結果の最大の長さも決まります。
imageなら最大 10 秒、videoなら最大 30 秒です(「向きと長さの関係」を参照)。 - 省略すると
imageが使われるため、10 秒を超えるモーション動画にはvideoを明示する必要があります。 - タスク作成時に残高から確保される金額も決まります。その向きで許される最長の結果の分です(「課金」を参照)。
値が正しくない場合
- リストにない値:
"character_orientation" must be one of: [image video]
キャラクターやシーンについての任意のテキスト指示です。動き自体は動画から取られます。
長さ:≤ 2500 文字
- 長さは文字数で数えます(CJK 文字は 1 文字として数えます)。空文字列も受け付けます。
値が正しくない場合
- 上限を超えている場合:
"prompt" has an unsupported length
出力解像度です。料金区分も兼ねており、1080p は 720p より 1 秒あたりの料金が高くなります。
指定できる値:720p, 1080p
デフォルト:720p
- 小文字のみです。省略すると
720pが使われます。
値が正しくない場合
- リストにない値(例:
480p、4k、1080P):"resolution" must be one of: [720p 1080p]
レスポンス
タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

