Crear una tarea de Motion Control de Kling

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

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

Enviar la solicitud de Motion Control

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.

Consultar la tarea

Use Obtener una tarea de Kling con el task_id devuelto. Continúe hasta que el estado sea succeed o failed.

Guardar el resultado

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:

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

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 y el protocolo de callback de Kling para obtener detalles de la API.

Autorizaciones

Authorization

string

header

requerido

Bearer authentication. Use your CometAPI API key.

Cuerpo

application/json

image_url

string

requerido

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>

requerido

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>

requerido

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.

Opciones disponibles:

image,

video

model_name

enum<string>

predeterminado: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.

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

predeterminado:yes

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

Opciones disponibles:

yes,

no

mode

enum<string>

predeterminado:std

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

Opciones 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

Respuesta

200 - application/json

Task accepted.

code

integer

requerido

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

message

string

requerido

Response message.

data

object

requerido

Show child attributes

Última modificación el 31 de julio de 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
  }
}

Moderación de contenido

Claves API

Crear una tarea de Motion Control de Kling

Medios obligatorios

Establezca el valor de orientación

Elija el modelo y el modo

Flujo de la tarea

Campos opcionales

Estructura de callback

Campos de resultado

Autorizaciones

Cuerpo

Respuesta

​Medios obligatorios

​Establezca el valor de orientación

​Elija el modelo y el modo

​Flujo de la tarea

​Campos opcionales

​Estructura de callback

​Campos de resultado

Autorizaciones

Cuerpo

Respuesta

Medios obligatorios

Establezca el valor de orientación

Elija el modelo y el modo

Flujo de la tarea

Campos opcionales

Estructura de callback

Campos de resultado