> ## 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.
# Crear una tarea de Motion Control de Kling
> Cree una tarea de Motion Control de Kling a partir de una imagen de personaje y un video de movimiento de referencia mediante la ruta compatible de CometAPI.
Use este endpoint para crear una tarea de Motion Control a partir de una imagen de personaje y un
video de referencia.
Esta página describe la ruta compatible de Motion Control. Kling Video 3.0
Motion Control utiliza un contrato de API independiente.
## Medios obligatorios
`image_url` acepta una URL pública o una cadena Base64 sin procesar.
* Use una imagen JPG, JPEG o PNG de 10 MB o menos.
* Establezca cada dimensión de la imagen entre 300 y 65.536 píxeles.
* Use una relación de aspecto entre 1:2,5 y 2,5:1.
* Envíe Base64 como la cadena codificada sin procesar, sin un
`data:image/...;base64,` prefijo.
* Muestre un único personaje sin obstrucciones, con un encuadre corporal que coincida con la
referencia de movimiento.
`video_url` acepta una URL pública de MP4 o MOV.
* Use un video de 100 MB o menos.
* Establezca el borde corto en al menos 340 píxeles.
* Establezca el borde largo en no más de 3850 píxeles.
* Use una toma continua con un personaje visible.
* Evite cortes, cambios de cámara y movimientos excesivamente rápidos.
Respete los límites de duración e inspeccione el `task_status` terminal anidado. Un
HTTP 200 externo o la respuesta `code: 0` confirma la respuesta de consulta, no un
resultado de generación correcto.
## Establezca el valor de orientación
`character_orientation` es obligatorio y acepta `image` o `video`.
| Valor | Duración del video de referencia |
| ------- | -------------------------------- |
| `image` | 3–10 segundos |
| `video` | 3–30 segundos |
Si usa `element_list`, establezca `character_orientation` en `video`.
## Elija el modelo y el modo
La ruta compatible acepta `kling-v2-6` y `kling-v3`. Ambos valores de modelo
aceptan ambos valores de modo:
| Modelo | `std` | `pro` |
| ------------ | -------- | -------- |
| `kling-v2-6` | Aceptado | Aceptado |
| `kling-v3` | Aceptado | Aceptado |
Si omite `model_name`, la solicitud usa `kling-v2-6`. Si omite `mode`,
la solicitud usa `std`. El valor `kling-v3` mantiene la estructura de solicitud compatible
descrita en esta página; no selecciona el contrato independiente de versión de ruta de Kling 3.0
de la ruta.
El contrato compatible no garantiza una resolución de salida fija. Inspeccione
cada video devuelto si su aplicación requiere dimensiones específicas.
`keep_original_sound` acepta `yes` o `no`. Si omite este campo, la
solicitud usa `yes`.
## Flujo de la tarea
Envíe la imagen de origen, el video de referencia y el valor de orientación. Seleccione un
modelo, modo y valor de sonido, o use sus valores predeterminados documentados. Guarde el
`task_id` devuelto.
Use [Obtener una tarea de Kling](./individual-queries) con el `task_id` devuelto.
Continúe hasta que el estado sea `succeed` o `failed`.
Descargue y guarde el resultado de inmediato. La documentación de la API compatible de Kling
indica que los videos generados se eliminan después de 30 días. No
confíe en que la URL devuelta permanecerá accesible durante los 30 días completos.
## Campos opcionales
| Campo | Estructura | Restricción |
| ------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `prompt` | Cadena, máximo de 2500 caracteres | Campo de texto opcional en la estructura de solicitud compatible. |
| `callback_url` | Cadena URI o cadena vacía | Omita el campo o use una cadena vacía cuando no haya una URI de callback configurada. |
| `external_task_id` | Cadena única para su cuenta | Correlaciona la tarea con su aplicación. No sustituye el `task_id` devuelto para las consultas de CometAPI. |
| `element_list` | Matriz con como máximo un objeto `{"element_id": 123}` | Combine este campo únicamente con `character_orientation: "video"`. |
| `watermark_info` | `{"enabled": boolean}` | La estructura de marca de agua compatible contiene solo el booleano `enabled`. |
## Estructura de callback
El esquema de callback de Legacy tiene la siguiente estructura:
```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"
}
]
}
}
```
El estado del callback puede ser `submitted`, `processing`, `succeed` o `failed`.
Los campos de resultado terminal solo están presentes cuando se devuelven para el estado terminal.
## Campos de resultado
| Campo | Tipo | Descripción |
| ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------ |
| `task_result.videos[].id` | Cadena | ID del video generado. |
| `task_result.videos[].url` | Cadena URI | URL de entrega del video generado. |
| `task_result.videos[].watermark_url` | Cadena URI | URL de entrega del video con marca de agua cuando la tarea devuelve una. |
| `task_result.videos[].duration` | Cadena | Duración del video generado en segundos. |
| `final_unit_deduction` | Cadena | Valor final de deducción de unidades devuelto con la tarea. |
| `final_balance_deduction` | `{"quota": string, "list_price": string}` | Valores finales de deducción de saldo devueltos con la tarea. |
El estado de la tarea es `submitted`, `processing`, `succeed` o `failed`.
Consulte la [referencia de la API de Motion Control de Kling](https://kling.ai/document-api/api/video/motion-control/legacy)
y el [protocolo de callback de Kling](https://kling.ai/document-api/api/get-started/callbacks)
para obtener detalles de la 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.
````