Créer une tâche 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
  }
}

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

Envoyer la requête Motion Control

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é.

Interroger la tâche

Utilisez Obtenir une tâche Kling avec le task_id renvoyé. Continuez jusqu’à ce que le statut soit succeed ou failed.

Stocker le résultat

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 :

{
  "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"
      }
    ]
  }
}

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 et le protocole de callback Kling pour les détails de l’API.

Autorisations

Authorization

string

header

requis

Bearer authentication. Use your CometAPI API key.

Corps

application/json

image_url

string

requis

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>

requis

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>

requis

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.

Options disponibles:

image,

video

model_name

enum<string>

défaut: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.

Options disponibles:

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>

défaut:yes

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

Options disponibles:

yes,

no

mode

enum<string>

défaut:std

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

Options disponibles:

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

Réponse

200 - application/json

Task accepted.

code

integer

requis

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

message

string

requis

Response message.

data

object

requis

Show child attributes

Dernière modification le 31 juillet 2026

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
  }
}

Modération de contenu

Clés API

Créer une tâche Kling Motion Control

Médias requis

Définir la valeur d’orientation

Choisir le modèle et le mode

Flux de la tâche

Champs facultatifs

Structure de callback

Champs de résultat

Autorisations

Corps

Réponse

​Médias requis

​Définir la valeur d’orientation

​Choisir le modèle et le mode

​Flux de la tâche

​Champs facultatifs

​Structure de callback

​Champs de résultat

Autorisations

Corps

Réponse

Médias requis

Définir la valeur d’orientation

Choisir le modèle et le mode

Flux de la tâche

Champs facultatifs

Structure de callback

Champs de résultat