ナビゲーションにスキップ

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 が返り、課金されません。利用を前提に組み込む前に、一覧を確認してください。

POST/v1/videos/tasks試してみる

このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。

モデル ID

2 つのモデルがこのエンドポイントと同じ入力を共有します。以下の値はゲートウェイの仕様から直接取得したものです。background_source を受け付けるのは Kling 3.0 Motion Control のみです。

モデル IDresolutioncharacter_orientationbackground_sourceキャラクター画像モーション動画選ぶ場面
kling-2.6-motion-control720p, 1080pimage, video—111 秒あたりの料金を抑えたく、背景がモーション動画のものでよい場合。
kling-3-motion-control720p, 1080pimage, videoinput_video, input_image11背景をモーション動画から取るか、キャラクター画像から取るか(background_source)を選びたい場合。1 秒あたりの料金は高くなります。

エンドポイントと認証

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 の後の再試行は改めて実行されます。

リクエストの流れ

1

タスクを作成する

下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。

2

完了を待つ

GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds(画像は 5 秒、動画は 8 秒)だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。

3

結果を保存する

succeeded の場合は、すべての data.output.media[].url をダウンロードし、必要なファイルを保存してください。結果 URL がいつまで利用できるかは保証されません。failed の場合は、data.error_code と data.error_message を確認してください。仮確保された金額は残高に戻されます。data.retryable は、同じリクエストをもう一度送れば成功する可能性があるかどうかを示します。

入力モード

モード必須の入力備考
モーション転送model、images(リンク 1 個)、reference_videos(リンク 1 個)キャラクター画像が動画の動きを演じます。prompt は任意です。それ以外は受け付けません(duration、aspect_ratio、音声、追加の参照素材は使えません)。

リクエストパラメーター

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 で拒否します。課金はされません。

メディアタスク作成前に確認される上限
動画1 本あたり 3~30 秒
  • タスク作成時に長さの上限が確認されるのはモーション動画だけです。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 が上限を決めます。

character_orientationキャラクターの向きが従うもの最長の結果作成時に残高から確保される分
image(デフォルト)キャラクター画像10 秒その解像度の単価で 10 秒分
videoモーション動画30 秒その解像度の単価で 30 秒分
  • タスク終了時に、生成された動画について報告された使用量から精算されます。通常は、その長さに 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>。

リクエスト例

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-2.6-motion-control",
"prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"resolution": "720p"
}'

モーション転送

動画リンクは、ご自身の 3~30 秒の MP4 または MOV に置き換えてください(公開のサンプル動画はありません)。character_orientation は省略しているため image が適用され、結果は最大 10 秒です。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-2.6-motion-control",
"prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"resolution": "720p"
}'

1080p、向きは動画に従う

10 秒を超えるクリップ向けです。video なら最大 30 秒の結果になります。動画リンクは、ご自身のクリップに置き換えてください。結果が長いほど、タスク作成時に残高から確保される金額が増えます。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-2.6-motion-control",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"resolution": "1080p",
"character_orientation": "video"
}'

レスポンス

タスクの作成(201)

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "kling-2.6-motion-control",
"capability_version": 1,
"media_type": "video",
"model": "kling-2.6-motion-control",
"status": "queued",
"stage": "queued",
"created_at": 1791993600,
"updated_at": 1791993600,
"completed_at": null,
"poll_after_seconds": 8,
"output": null,
"usage": {
"credits_reserved": 0.6,
"credits_settled": 0,
"credits_refunded": 0,
"credits_charged": 0.6,
"billable_duration_seconds": 10
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}
フィールド型説明
data.idstringタスク ID です。task_ の後に英数字 32 文字が続きます。ポーリングや Webhook イベントとの照合に使います。
data.objectstring常に task です。
data.task_kindstringimage または video です。
data.capability_idstring送信したモデル ID です。
data.capability_versionintegerモデルの仕様バージョンです。現在は 1 です。
data.media_typestringimage または video です。
data.modelstring送信したモデル ID です(capability_id と同じ)。
data.statusstringqueued、processing、succeeded、failed のいずれかです。最終状態は後ろの 2 つだけです。
data.stagestringstatus と同じ値です。古いクライアント向けに残されています。
data.created_atintegerタスクの作成日時(Unix 秒)です。
data.updated_atinteger最終更新日時(Unix 秒)です。
data.completed_atinteger | nullタスクの完了日時(Unix 秒)です。実行中は null です。
data.poll_after_secondsinteger実行中のみ。次のポーリングまでに待つ秒数です(画像は 5、動画は 8)。
data.typical_secondsobject実行中のみ、直近のタスクが十分にある場合に含まれます。直近 window の samples 件のタスクについて、完了までの時間(秒)の p50 と p90 を示します。
data.outputobject | null結果です。status が succeeded になるまでは null です。下の出力フィールドを参照してください。
data.usage.credits_reservednumberタスク作成時に残高から仮確保された金額(USD)です。
data.usage.credits_chargednumberこのタスクの料金(USD)です。失敗したタスクでは 0 です。
data.usage.credits_settlednumber最終的に差し引かれた金額(USD)です。タスクが成功した時点で設定され、それ以外では 0 です。
data.usage.credits_refundednumber残高に戻された金額(USD)です。失敗したタスクでは、返金が記録された時点で仮確保した金額と一致します。
data.usage.billable_duration_secondsinteger動画のみ。料金の算定に使われた秒数です。モデルが長さを報告しない場合は含まれません。
data.request_idstringリクエスト ID です。サポートに問い合わせる際に添えてください。
data.error_codestring | null失敗コードです。タスクが失敗した場合以外は null です。
data.error_messagestring | null何が問題で、何を変更すればよいかを示します。タスクが失敗した場合以外は null です。

完了したタスク

GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "kling-2.6-motion-control",
"capability_version": 1,
"media_type": "video",
"model": "kling-2.6-motion-control",
"status": "succeeded",
"stage": "succeeded",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": {
"media": [
{
"type": "video",
"url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
"mime_type": "video/mp4"
}
],
"r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
},
"usage": {
"credits_reserved": 0.6,
"credits_settled": 0.6,
"credits_refunded": 0,
"credits_charged": 0.6,
"billable_duration_seconds": 10
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}

出力フィールド

フィールド型説明
output.mediaobject[]生成されたファイルです。このモデルでは動画 1 本です。
output.media[].typestring常に video です。
output.media[].urlstring保存された動画への HTTPS リンクです。ダウンロードして保管してください。保持期間は保証されません。
output.media[].mime_typestring保存された動画の MIME タイプです。例:video/mp4。
output.r2_urlstring古いクライアント向けに、動画 URL を再掲したものです。代わりに media を読んでください。

失敗したタスク

失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "kling-2.6-motion-control",
"capability_version": 1,
"media_type": "video",
"model": "kling-2.6-motion-control",
"status": "failed",
"stage": "failed",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": null,
"usage": {
"credits_reserved": 0.6,
"credits_settled": 0,
"credits_refunded": 0.6,
"credits_charged": 0,
"billable_duration_seconds": 10
},
"retryable": true,
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": "processing_failed",
"error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
}
}
フィールド型説明
data.error_codestringbad_request と content_policy_violation(リクエストを修正してください)、または processing_unavailable、processing_timeout、processing_failed、result_transfer_failed(時間をおいて再試行してください)のいずれかです。エラーを参照してください。
data.error_messagestring問題と対処方法を示す文です。
data.retryableboolean失敗したタスクにのみ含まれます。同じリクエストをもう一度送れば成功する可能性がある場合は true です。
data.usageobject返金が記録された時点(通常はタスクが失敗した瞬間)で、credits_charged と credits_settled は 0 になり、credits_refunded は credits_reserved と一致します。

完全なコード例

タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
# One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
for attempt in range(3):
response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
if response.status_code in (429, 503) and attempt < 2:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
break
try:
payload = response.json()
except ValueError: # an edge error page is not JSON
response.raise_for_status()
raise
if not response.ok:
error = payload["error"]
raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
deadline = time.monotonic() + timeout_seconds
while time.monotonic() < deadline:
response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
if response.status_code == 429 or response.status_code >= 500:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
response.raise_for_status()
task = response.json()["data"]
if task["status"] in ("succeeded", "failed"):
return task
time.sleep(task.get("poll_after_seconds", 5))
raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
"model": "kling-2.6-motion-control",
"prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
print(item["url"])

課金

  • これらの料金はモデルが一覧に載った後に適用されます。それまでは作成リクエストは拒否され、課金されません。
  • 料金は、完成した動画の秒数に応じて、resolution ごとの単価で決まります。character_orientation とプロンプトは単価に影響しません。下の表は 8 秒の結果の料金です。
  • 結果はモーション動画と同じ長さになるため、タスク作成時には最終的な料金が決まっていません。ゲートウェイは、その解像度の単価で、向きが許す最長の結果分を確保します。image なら 10 秒、video なら 30 秒です。目安は、image で 0.60(720p)または0.60(720p)または 1.00(1080p)、video で 1.80(720p)または1.80(720p)または 3.00(1080p)です。残高がこの金額を満たしていない場合、作成の呼び出しは 402 insufficient_credits で失敗します。
  • タスクが終了すると、生成された動画について報告された使用量から精算されます。通常は、その長さに 1 秒あたりの定価を掛けた金額です。確保額の残りは返金されます。使用量が報告されない場合は、確保額が課金されます。課金された金額は usage.credits_charged と usage.credits_settled に表示されます。このモデルの usage.billable_duration_seconds は、作成時に確保した秒数(10 または 30)を示し、完成した動画の長さではありません。支払った金額は credits のフィールドで確認してください。
  • 失敗したタスク(送信後にモデレーションで拒否されたものを含む)は全額返金されます。タスクが作成される前に拒否されたリクエストには課金されません。

現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。

オプション定価(USD)
8 秒 · 720p$0.48
8 秒 · 1080p$0.8

よくあるエラー

エラーまたは症状原因対処
400 field "duration" is not supported by model kling-2.6-motion-controlこのモデルが受け付けないフィールドです(aspect_ratio、seed、generate_audio、task_type なども同様です)。そのフィールドを削除してください。長さはモーション動画に従います。
400 "images" accepts at most 1 items or "reference_videos" accepts at most 1 itemsキャラクター画像またはモーション動画が 2 個以上あります。各リストにリンクをちょうど 1 個送ってください。
400 "reference_videos" is requiredモーション動画がありません。このモデルにはテキストのみ・画像のみのモードがありません。reference_videos と images にそれぞれリンクを 1 個送ってください。
400 reference_videos[0] is 2 seconds long; this model takes reference video of 3 to 30 seconds.モーション動画が 3 秒未満、または 30 秒を超えています。クリップを切り詰めるか差し替えてください。課金はされていません。
400 reference_videos[0] could not be downloaded: the URL returned HTTP 404.リンクがエラーまたは空のファイルを返しています。クリップを公開 HTTPS リンクで配置するか、POST /v1/files でアップロードしてください。
400 "resolution" must be one of: [720p 1080p]480p、4k、または 1080P のような大文字表記です。720p または 1080p を送ってください。
400 field "background_source" is not supported by model kling-2.6-motion-controlbackground_source があるのは kling-3-motion-control だけです。削除するか、kling-3-motion-control に切り替えてください。
402 insufficient_credits残高が作成時に確保される金額(向きが許す最長の結果分。image は 10 秒、video は 30 秒)に足りません。チャージするか、character_orientation: "image" と 10 秒以内のクリップを使ってください。確保額が少なくなります。
タスク作成時の 503 processing_unavailable現在このモデルは提供されていません。GET /v1/media/models に載っていません。課金はされていません。一覧を確認してから、バックオフを入れて再試行してください。
タスクが failed となり、content_policy_violation が返るプロンプト、入力、または結果がモデレーションで拒否されました。入力を変更してください。そのまま再試行しても再び失敗します。課金はされません。

HTTP エラー早見表

タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。

{
"error": {
"code": "bad_request",
"message": "\"prompt\" is required",
"retryable": false,
"request_id": "req_5f0c2a9e4b7d4e31"
}
}
HTTP ステータスerror.code対処方法
400bad_request, content_policy_violationリクエストを修正してください。メッセージにフィールド名が示されます。そのまま再試行しないでください。
401missing_api_key, invalid_api_key(古いクライアントでは unauthorized が返ることがあります)有効なキーを Authorization: Bearer <key> で送信してください。
402insufficient_credits残高をチャージするか、キーのクォータを引き上げてから、再度送信してください。
403forbiddenこのキーまたはアカウントでは、このモデルを利用できない可能性があります(たとえば、無料クレジットは一部のモデルにのみ使えます)。そのまま再試行しないでください。
404not_foundGET /v1/tasks/{task_id} の場合:このキーのアカウントに該当するタスクが存在しません。ID を確認してください。
409idempotency_conflict新しい Idempotency-Key を使うか、同じキーの最初のリクエストが完了するまで待ってください。
429rate_limit_exceededRetry-After の秒数(error.retry_after_seconds にも含まれます)だけ待ってから再試行してください。
500internal_errorバックオフを入れて再試行してください。解消しない場合は、request_id を添えてサポートにお問い合わせください。
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failed課金はされていません。指数バックオフで再試行してください。

2 つのモデルの違い

Kling 2.6 Motion ControlKling 3.0 Motion Control
入力キャラクター画像 1 枚、3~30 秒のモーション動画 1 本同じ
resolution720p, 1080p同じ
character_orientationimage(デフォルト)、video同じ
background_source受け付けないinput_video(デフォルト)、input_image
1 秒あたりの料金低い高い(各ページの料金表を参照)

認証

AuthorizationBearer

API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。

ヘッダー

Idempotency-Keystringオプション<=255 characters

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエスト

This endpoint expects an object.
imageslist of strings必須

キャラクター画像で、リンクはちょうど 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
modelenum必須

実行するモデルです。

値:kling-2.6-motion-control

値が正しくない場合

  • 指定がない場合:"model" is required
  • 画像モデルをこのエンドポイントに送った場合:"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
許可された値:
reference_videoslist of strings必須

モーション動画で、リンクはちょうど 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.
character_orientationenumオプションデフォルト値 image

キャラクターの向きを、キャラクター画像(image)とモーション動画(video)のどちらに合わせるかを指定します。

指定できる値:image, video

デフォルト:image

  • 結果の最大の長さも決まります。image なら最大 10 秒、video なら最大 30 秒です(「向きと長さの関係」を参照)。
  • 省略すると image が使われるため、10 秒を超えるモーション動画には video を明示する必要があります。
  • タスク作成時に残高から確保される金額も決まります。その向きで許される最長の結果の分です(「課金」を参照)。

値が正しくない場合

  • リストにない値:"character_orientation" must be one of: [image video]
許可された値:
promptstringオプション<=2500 characters

キャラクターやシーンについての任意のテキスト指示です。動き自体は動画から取られます。

長さ:≤ 2500 文字

  • 長さは文字数で数えます(CJK 文字は 1 文字として数えます)。空文字列も受け付けます。

値が正しくない場合

  • 上限を超えている場合:"prompt" has an unsupported length
resolutionenumオプションデフォルト値 720p

出力解像度です。料金区分も兼ねており、1080p は 720p より 1 秒あたりの料金が高くなります。

指定できる値:720p, 1080p

デフォルト:720p

  • 小文字のみです。省略すると 720p が使われます。

値が正しくない場合

  • リストにない値(例:480p、4k、1080P):"resolution" must be one of: [720p 1080p]
許可された値:

レスポンス

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

エラー

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error