> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kling Motion Control タスクを作成する
> 互換性のある CometAPI ルートを使用して、キャラクター画像と参照モーション動画から Kling Motion Control タスクを作成します。
このエンドポイントを使用して、キャラクター画像と
参照動画から 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` が使用されます。
## タスクフロー
ソース画像、参照動画、orientation 値を送信します。
モデル、モード、sound 値を選択するか、文書化されているデフォルト値を使用します。返された
`task_id` を保存します。
タスクの取得には、 [Get a Kling task](./individual-queries) を返された `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 コールバック スキーマの構造は次のとおりです。
```json theme={null}
{
"task_id": "",
"task_status": "succeed",
"task_status_msg": "",
"created_at": 1785398400000,
"updated_at": 1785398460000,
"final_unit_deduction": "",
"final_balance_deduction": {
"quota": "",
"list_price": ""
},
"task_info": {
"external_task_id": ""
},
"task_result": {
"videos": [
{
"id": "",
"url": "https://media.example.com/.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 リファレンス](https://kling.ai/document-api/api/video/motion-control/legacy)
および [Kling コールバックプロトコル](https://kling.ai/document-api/api/get-started/callbacks)
を参照してください。
## OpenAPI
````yaml api/openapi/video/kling/post-motion-control.openapi.json POST /kling/v1/videos/motion-control
openapi: 3.1.0
info:
title: Kling Motion Control API
version: 1.0.0
description: >-
Create a Kling Motion Control task from a character image and a reference
motion video.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/videos/motion-control:
post:
summary: Create a Kling Motion Control task
description: >-
Submit a character image and a reference motion video. The response
contains a task ID that you can use for status queries.
operationId: create_kling_motion_control
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image_url
- video_url
- character_orientation
properties:
model_name:
type: string
description: >-
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.
enum:
- kling-v2-6
- kling-v3
default: kling-v2-6
image_url:
type: string
description: >-
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:
type: string
format: uri
description: >-
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`.
prompt:
type: string
maxLength: 2500
description: >-
Optional text field in the compatible request structure.
Maximum 2500 characters.
keep_original_sound:
type: string
description: >-
Compatible string enum. Accepted values are `yes` and `no`.
Omitted requests use `yes`.
enum:
- 'yes'
- 'no'
default: 'yes'
character_orientation:
type: string
description: >-
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.
enum:
- image
- video
mode:
type: string
description: >-
Both compatible models accept `std` and `pro`. Omitted
requests use `std`.
enum:
- std
- pro
default: std
callback_url:
description: >-
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.
oneOf:
- type: string
format: uri
- type: string
const: ''
external_task_id:
type: string
description: >-
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:
type: array
maxItems: 1
description: >-
Optional compatible Element structure. Provide at most one
object, and combine this field only with
`character_orientation: video`.
items:
type: object
required:
- element_id
properties:
element_id:
type: integer
format: int64
description: Kling Element ID in the compatible structure.
additionalProperties: false
watermark_info:
type: object
description: Optional compatible watermark structure.
required:
- enabled
properties:
enabled:
type: boolean
description: Boolean flag in the compatible watermark structure.
additionalProperties: false
example:
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
examples:
Image URL:
summary: Use a public character image URL
value:
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
Image base64:
summary: Use a raw Base64 character image
value:
model_name: kling-v3
image_url:
video_url: https://your-video-host.example.com/reference-motion.mp4
prompt: Studio scene.
keep_original_sound: 'no'
character_orientation: video
mode: pro
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
type: integer
description: >-
Response code. A value of 0 indicates that the request was
accepted.
message:
type: string
description: Response message.
data:
type: object
required:
- task_id
- task_status
- task_info
- created_at
- updated_at
properties:
task_id:
type: string
description: System-generated task ID for status queries.
task_status:
type: string
description: Task state after submission.
const: submitted
task_status_msg:
type: string
description: Status detail when returned.
task_info:
type: object
description: Additional task metadata. The object can be empty.
additionalProperties: true
created_at:
type: integer
format: int64
description: Task creation timestamp in milliseconds.
updated_at:
type: integer
format: int64
description: Last task update timestamp in milliseconds.
example:
code: 0
message: SUCCEED
data:
task_id:
task_status: submitted
task_info: {}
created_at: 1785398400000
updated_at: 1785398400000
x-codeSamples:
- lang: Shell
label: Image URL
source: |
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"
}'
- lang: Python
label: Image URL
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/motion-control",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"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",
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Image URL
source: |
const response = await fetch(
"https://api.cometapi.com/kling/v1/videos/motion-control",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
},
);
const result = await response.json();
console.log(result.code, result.data?.task_id);
- lang: Shell
label: Image base64
source: |
curl https://api.cometapi.com/kling/v1/videos/motion-control \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"model_name": "kling-v3",
"image_url": "",
"video_url": "https://your-video-host.example.com/reference-motion.mp4",
"prompt": "Studio scene.",
"keep_original_sound": "no",
"character_orientation": "video",
"mode": "pro"
}
JSON
- lang: Python
label: Image base64
source: |
import base64
import os
import requests
with open("character.png", "rb") as image_file:
image_base64 = base64.b64encode(image_file.read()).decode("ascii")
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/motion-control",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"model_name": "kling-v3",
"image_url": image_base64,
"video_url": "https://your-video-host.example.com/reference-motion.mp4",
"prompt": "Studio scene.",
"keep_original_sound": "no",
"character_orientation": "video",
"mode": "pro",
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Image base64
source: >
import { readFile } from "node:fs/promises";
const imageBase64 = (await
readFile("character.png")).toString("base64");
const response = await fetch(
"https://api.cometapi.com/kling/v1/videos/motion-control",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model_name: "kling-v3",
image_url: imageBase64,
video_url: "https://your-video-host.example.com/reference-motion.mp4",
prompt: "Studio scene.",
keep_original_sound: "no",
character_orientation: "video",
mode: "pro",
}),
},
);
const result = response.json();
console.log(result.code, result.data?.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````