> ## 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.
# Créer une tâche Kling Motion Control
> Créez une tâche Kling Motion Control à partir d’une image de personnage et d’une vidéo de mouvement de référence avec la route CometAPI compatible.
Utilisez ce point de terminaison pour créer une tâche Motion Control à partir d’une image de personnage et d’une
vidéo de référence.
Cette page décrit la route Motion Control compatible. Kling Video 3.0
Motion Control utilise un contrat API distinct.
## Médias requis
`image_url` accepte une URL publique ou une chaîne Base64 brute.
* Utilisez une image JPG, JPEG ou PNG de 10 Mo ou moins.
* Définissez chaque dimension de l’image entre 300 et 65 536 pixels.
* Utilisez un rapport hauteur/largeur compris entre 1:2,5 et 2,5:1.
* Envoyez Base64 sous la forme d’une chaîne encodée brute, sans
`data:image/...;base64,` préfixe.
* Affichez un seul personnage non obstrué, avec un cadrage du corps correspondant au
référentiel de mouvement.
`video_url` accepte une URL publique MP4 ou MOV.
* Utilisez une vidéo de 100 Mo ou moins.
* Définissez le petit côté sur au moins 340 pixels.
* Définissez le grand côté sur 3 850 pixels au maximum.
* Utilisez un plan continu avec un seul personnage visible.
* Évitez les coupes, les changements de caméra et les mouvements excessivement rapides.
Respectez les limites de durée et examinez le `task_status` terminal imbriqué. Une
réponse HTTP 200 externe ou un `code: 0` de réponse confirme la réponse à la requête, et non un
résultat de génération réussi.
## Définir la valeur d’orientation
`character_orientation` est obligatoire et accepte `image` ou `video`.
| Valeur | Durée de la vidéo de référence |
| ------- | ------------------------------ |
| `image` | 3–10 secondes |
| `video` | 3–30 secondes |
Si vous utilisez `element_list`, définissez alors `character_orientation` sur `video`.
## Choisir le modèle et le mode
La route compatible accepte `kling-v2-6` et `kling-v3`. Les deux valeurs de modèle
acceptent les deux valeurs de mode :
| Modèle | `std` | `pro` |
| ------------ | ------- | ------- |
| `kling-v2-6` | Accepté | Accepté |
| `kling-v3` | Accepté | Accepté |
Si vous omettez `model_name`, la requête utilise `kling-v2-6`. Si vous omettez `mode`,
la requête utilise `std`. La valeur `kling-v3` conserve la forme de requête compatible
décrite sur cette page ; elle ne sélectionne pas le contrat distinct de Kling 3.0 basé sur la version du chemin
d’accès.
Le contrat compatible ne garantit pas une résolution de sortie fixe. Vérifiez
chaque vidéo renvoyée si votre application exige des dimensions spécifiques.
`keep_original_sound` accepte `yes` ou `no`. Si vous omettez ce champ, la
requête utilise `yes`.
## Flux de la tâche
Envoyez l’image source, la vidéo de référence et la valeur d’orientation. Sélectionnez un
modèle, un mode et une valeur de son, ou utilisez leurs valeurs par défaut documentées. Stockez le
`task_id` renvoyé.
Utilisez [Obtenir une tâche Kling](./individual-queries) avec le `task_id` renvoyé.
Continuez jusqu’à ce que le statut soit `succeed` ou `failed`.
Téléchargez et stockez rapidement le résultat. La documentation de l’API compatible de Kling
indique que les vidéos générées sont supprimées après 30 jours. Ne
comptez pas sur l’accessibilité de l’URL renvoyée pendant l’intégralité des 30 jours.
## Champs facultatifs
| Champ | Structure | Contrainte |
| ------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `prompt` | Chaîne, 2 500 caractères maximum | Champ texte facultatif dans la structure de requête compatible. |
| `callback_url` | Chaîne URI ou chaîne vide | Omettez le champ ou utilisez une chaîne vide lorsqu’aucune URI de callback n’est configurée. |
| `external_task_id` | Chaîne unique pour votre compte | Associe la tâche à votre application. Il ne remplace pas le `task_id` renvoyé pour les requêtes CometAPI. |
| `element_list` | Tableau contenant au plus un objet `{"element_id": 123}` | Combinez ce champ uniquement avec `character_orientation: "video"`. |
| `watermark_info` | `{"enabled": boolean}` | La structure de filigrane compatible contient uniquement le booléen `enabled`. |
## Structure de callback
Le schéma de callback Legacy présente la structure suivante :
```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"
}
]
}
}
```
Le statut de callback peut être `submitted`, `processing`, `succeed` ou `failed`.
Les champs de résultat terminal sont présents uniquement lorsqu’ils sont renvoyés pour l’état terminal.
## Champs de résultat
| Champ | Type | Description |
| ------------------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------- |
| `task_result.videos[].id` | Chaîne | ID de la vidéo générée. |
| `task_result.videos[].url` | Chaîne URI | URL de livraison de la vidéo générée. |
| `task_result.videos[].watermark_url` | Chaîne URI | URL de livraison de la vidéo avec filigrane lorsque la tâche en renvoie une. |
| `task_result.videos[].duration` | Chaîne | Durée de la vidéo générée en secondes. |
| `final_unit_deduction` | Chaîne | Valeur finale de déduction d’unités renvoyée avec la tâche. |
| `final_balance_deduction` | `{"quota": string, "list_price": string}` | Valeurs finales de déduction du solde renvoyées avec la tâche. |
Le statut de la tâche est `submitted`, `processing`, `succeed` ou `failed`.
Consultez la [référence de l’API Kling Motion Control](https://kling.ai/document-api/api/video/motion-control/legacy)
et le [protocole de callback Kling](https://kling.ai/document-api/api/get-started/callbacks)
pour les détails de l’API.
## 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.
````