Kling 3.0 Motion Control

POST https://api.beatapi.io/v1/videos/tasks

全身の動きを転写し、人物の向きと背景の参照元を選択できます。720p・1080p に対応しています。向きを画像に合わせる場合は最大 10 秒、動画に合わせる場合は最大 30 秒です。

対応する生成モード

非同期処理の流れ： タスクを作成して data.id を保存し、GET /v1/tasks/{task_id} でステータスをポーリングします。succeeded の場合は data.output.media から結果を取得します。failed の場合は data.error_code と data.error_message を確認し、エラーと再試行の方針に従って対処してください。

ローカルファイルを使う場合： 先に入力ファイルをアップロードし、返された data.url を指定してください。

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

model   string   必須

kling-3-motion-control を指定してください。

固定値: kling-3-motion-control

prompt   string   任意

動きやシーンに関する任意の指示です。

文字数: 最大 2500 文字

images   string[]   必須

現在のアカウントで /v1/files にアップロードして取得した人物画像の URL を、1 個指定します。ファイルサイズは最大 10 MB です。

要素数: 1 – 1 件

reference_videos   string[]   必須

現在のアカウントで /v1/files にアップロードして取得した、3～30 秒の MP4/MOV 動画の URL を 1 個指定します。ファイルサイズは最大 100 MB です。検出された動画の長さに基づいて課金されます。

要素数: 1 – 1 件

resolution   enum<string>   任意

出力解像度と、対応する秒単価の区分です。

選択肢: 720p, 1080p
デフォルト値: "720p"

character_orientation   enum<string>   任意

人物の向きを画像に合わせる場合、動作動画は最大 10 秒です。動画に合わせる場合は最大 30 秒です。

選択肢: image, video
デフォルト値: "image"

background_source   enum<string>   任意

動作動画または人物画像の背景を引き継ぎます。

選択肢: input_video, input_image
デフォルト値: "input_video"

リクエスト例

モーション転写

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-3-motion-control",
  "prompt": "Preserve the character and transfer the full-body motion precisely.",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://media.beatapi.io/inputs/motion.mp4"
  ],
  "resolution": "1080p",
  "character_orientation": "image",
  "background_source": "input_video"
}'

レスポンス

リクエストが成功すると、HTTP 201 が返されます。

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": null,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 2.1,
      "credits_charged": 2.1,
      "billable_duration_seconds": 15,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

エラー