Kling Motion Control タスクを作成する

POST

kling

videos

motion-control

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

このエンドポイントを使用して、キャラクター画像と参照動画から Motion Control タスクを作成します。

このページでは、互換性のある Motion Control ルートについて説明します。Kling Video 3.0 Motion Control では、別の API 契約を使用します。

必要なメディア

image_url は、パブリック URL または生の Base64 文字列を受け付けます。

10 MB 以下の JPG、JPEG、または PNG 画像を使用してください。
各画像の寸法は 300～65,536 ピクセルにしてください。
アスペクト比は 1:2.5～2.5:1 にしてください。
Base64 は、生のエンコード文字列として送信し、 data:image/...;base64, プレフィックスは含めないでください。
モーション参照と一致する全身構図で、遮蔽物のないキャラクターを 1 人表示してください。

video_url は、パブリックな MP4 または MOV の URL を受け付けます。

100 MB 以下の動画を使用してください。
短辺は少なくとも 340 ピクセルにしてください。
長辺は 3850 ピクセル以下にしてください。
表示されるキャラクターが 1 人の連続したショットを使用してください。
カット、カメラ変更、過度に速い動きは避けてください。

再生時間の制限に従い、ネストされた終端の task_status を確認してください。外側の HTTP 200 またはレスポンスの code: 0 はクエリ応答を確認するものであり、生成の成功結果を示すものではありません。

orientation 値を設定する

character_orientation は必須であり、image または video を受け付けます。

値	参照動画の長さ
`image`	3～10 秒
`video`	3～30 秒

element_list を使用する場合は、character_orientation を video に設定してください。

モデルとモードを選択する

互換性のあるルートは kling-v2-6 と kling-v3 を受け付けます。どちらのモデル値も両方のモード値を受け付けます。

モデル	`std`	`pro`
`kling-v2-6`	使用可能	使用可能
`kling-v3`	使用可能	使用可能

model_name を省略した場合、リクエストでは kling-v2-6 が使用されます。mode を省略した場合、リクエストでは std が使用されます。kling-v3 値は、互換リクエストの形式を維持します。このページで説明する形式であり、別の Kling 3.0 パスバージョン契約を選択するものではありません。互換契約では固定の出力解像度は保証されません。アプリケーションで特定の寸法が必要な場合は、返された各動画を確認してください。 keep_original_sound は yes または no を受け付けます。このフィールドを省略した場合、リクエストでは yes が使用されます。

タスクフロー

Motion Control リクエストを送信する

ソース画像、参照動画、orientation 値を送信します。モデル、モード、sound 値を選択するか、文書化されているデフォルト値を使用します。返された task_id を保存します。

タスクをポーリングする

タスクの取得には、 Get a Kling task を返された task_id とともに使用します。ステータスが succeed または failed になるまで続けてください。

結果を保存する

結果を速やかにダウンロードして保存してください。Kling の互換 API ドキュメントでは、生成された動画は 30 日後に削除されるとされています。返された URL が 30 日間ずっとアクセス可能であることを前提にしないでください。

任意フィールド

フィールド	構造	制約
`prompt`	最大 2500 文字の文字列	互換リクエスト構造内の任意のテキストフィールドです。
`callback_url`	URI 文字列または空文字列	コールバック URI が設定されていない場合は、フィールドを省略するか空文字列を使用してください。
`external_task_id`	アカウント内で一意の文字列	タスクをアプリケーションに関連付けます。CometAPI クエリでは、返された `task_id` の代わりにはなりません。
`element_list`	最大 1 個の `{"element_id": 123}` オブジェクトを含む配列	このフィールドは、以下とのみ組み合わせてください。 `character_orientation: "video"`.
`watermark_info`	`{"enabled": boolean}`	互換性のあるウォーターマーク構造には、`enabled` ブール値のみが含まれます。

コールバック構造

Legacy コールバックスキーマの構造は次のとおりです。

{
  "task_id": "<task_id>",
  "task_status": "succeed",
  "task_status_msg": "",
  "created_at": 1785398400000,
  "updated_at": 1785398460000,
  "final_unit_deduction": "<value>",
  "final_balance_deduction": {
    "quota": "<value>",
    "list_price": "<value>"
  },
  "task_info": {
    "external_task_id": "<your_unique_id>"
  },
  "task_result": {
    "videos": [
      {
        "id": "<video_id>",
        "url": "https://media.example.com/<file_id>.mp4",
        "duration": "6.4"
      }
    ]
  }
}

コールバックのステータスには、submitted、processing、succeed、または failed を指定できます。終端結果フィールドは、終端状態で返される場合にのみ存在します。

結果フィールド

フィールド	型	説明
`task_result.videos[].id`	文字列	生成された動画 ID。
`task_result.videos[].url`	URI 文字列	生成された動画の配信 URL。
`task_result.videos[].watermark_url`	URI 文字列	タスクが返した場合の、ウォーターマーク付き動画の配信 URL。
`task_result.videos[].duration`	文字列	生成された動画の長さ（秒）。
`final_unit_deduction`	文字列	タスクとともに返される最終ユニット控除値。
`final_balance_deduction`	`{"quota": string, "list_price": string}`	タスクとともに返される最終残高控除値。

タスクのステータスは submitted、processing、succeed、または failed です。

API の詳細については、 Kling Motion Control API リファレンスおよび Kling コールバックプロトコルを参照してください。

承認

Authorization

string

header

必須

Bearer authentication. Use your CometAPI API key.

ボディ

application/json

image_url

string

必須

Character image as a public URL or a raw Base64 string. Send raw Base64 without a data:image/...;base64, prefix; data-URI input is outside the compatible contract. Supported formats are JPG, JPEG, and PNG. The image must be 10 MB or smaller. Its width and height must each be from 300 through 65,536 pixels, and its aspect ratio must be between 1:2.5 and 2.5:1.

video_url

string<uri>

必須

Public reference motion video URL. Use an MP4 or MOV file that is 100 MB or smaller. The short edge must be at least 340 pixels, and the long edge must not exceed 3850 pixels. The video must be at least 3 seconds long. The maximum duration depends on character_orientation.

character_orientation

enum<string>

必須

Required compatible string enum. With image, the reference video can be 3 to 10 seconds long. With video, the reference video can be 3 to 30 seconds long.

利用可能なオプション:

image,

video

model_name

enum<string>

デフォルト:kling-v2-6

Model ID for this compatible Motion Control request. Omit this field to use kling-v2-6. The kling-v3 value keeps this compatible request shape; it does not select the separate Kling 3.0 path-version contract.

利用可能なオプション:

kling-v2-6,

kling-v3

prompt

string

Optional text field in the compatible request structure. Maximum 2500 characters.

Maximum string length: 2500

keep_original_sound

enum<string>

デフォルト:yes

Compatible string enum. Accepted values are yes and no. Omitted requests use yes.

利用可能なオプション:

yes,

no

mode

enum<string>

デフォルト:std

Both compatible models accept std and pro. Omitted requests use std.

利用可能なオプション:

std,

pro

callback_url

Optional callback field in the compatible structure. Provide a URI, or omit the field or send an empty string when no callback URI is configured.

external_task_id

string

Optional ID for correlation in your application. The value must be unique for your account. Store the returned task_id for CometAPI status queries.

element_list

object[]

Optional compatible Element structure. Provide at most one object, and combine this field only with character_orientation: video.

Maximum array length: 1

Show child attributes

watermark_info

object

Optional compatible watermark structure.

Show child attributes

レスポンス

200 - application/json

Task accepted.

code

integer

必須

Response code. A value of 0 indicates that the request was accepted.

message

string

必須

Response message.

data

object

必須

Show child attributes

最終更新日 2026年7月31日

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

コンテンツモデレーション

APIキー

Kling Motion Control タスクを作成する

必要なメディア

orientation 値を設定する

モデルとモードを選択する

タスクフロー

任意フィールド

コールバック構造

結果フィールド

承認

ボディ

レスポンス

​必要なメディア

​orientation 値を設定する

​モデルとモードを選択する

​タスクフロー

​任意フィールド

​コールバック構造

​結果フィールド

承認

ボディ

レスポンス

必要なメディア

orientation 値を設定する

モデルとモードを選択する

タスクフロー

任意フィールド

コールバック構造

結果フィールド