API de control de movimiento de Kling (v3 y v2.6)

Q: ¿Puedo fijar la duración de un video de control de movimiento?

No. duration debe omitirse, y enviarlo devuelve 400. El resultado dura lo mismo que el video de movimiento que proporcione, así que recorte el clip original para controlar la duración y el costo.

Q: ¿Cuánto puede durar el video de movimiento?

Depende de extra.character_orientation: hasta 10 segundos con image y hasta 30 segundos con video (el valor predeterminado). Un clip más largo falla aproximadamente medio minuto después de iniciar la tarea con invalid_request y no se factura. Para un resultado más largo, divida el movimiento en varios clips, procese cada uno y únalos.

Respuesta corta: el control de movimiento de Kling toma una imagen de una persona y un video de movimiento, y hace que la persona de la imagen ejecute el movimiento del video. En HopBase se invoca con el modelo kling-v3-motion-control (720p, 1080p, 2K o 4K) o kling-v2-6-motion-control (720p o 1080p). Ambos usan el mismo endpoint asíncrono que el resto de modelos Kling: POST https://api.hop-base.com/v1/video/generate y, después, consultas periódicas a GET /v1/video/tasks/{task_id}. Envíe exactamente una imagen y un video, y omita duration, porque el resultado dura lo mismo que el video de movimiento. El único parámetro adicional es extra.character_orientation (image o video). Se factura por segundo de video generado, las tareas fallidas no tienen costo y los enlaces de resultado son válidos durante 24 horas. El paso que más falla es el propio video de movimiento: debe mostrar el torso completo de una persona real, de la cabeza a la cintura.

Qué es el control de movimiento y cuándo usarlo en lugar de avatar o sincronización labial

Kling ofrece tres flujos para animar a una persona, y cada uno responde a una necesidad distinta:

Modelo	Entrada	Qué se mueve	Duración del resultado
`kling-v3-motion-control` / `kling-v2-6-motion-control`	1 imagen de persona + 1 video de movimiento	Todo el cuerpo copia el movimiento del video	Igual que el video de movimiento
`kling-avatar`	1-5 imágenes de persona + 1 pista de audio	Rostro y boca, guiados por el audio	Igual que el audio
`kling-lip-sync`	Un video existente + audio nuevo	Solo la boca, resincronizada con el audio nuevo	Igual que el original

Use el control de movimiento cuando tenga un movimiento (un baile, un gesto de demostración de producto, un ciclo de caminata, el lenguaje corporal de un presentador) y quiera que lo ejecute otro personaje: una mascota de marca, un modelo con ropa nueva o un personaje generado. Si el personaje solo necesita hablar, use avatar o sincronización labial; nuestra guía de humanos digitales de Kling cubre ambos casos.

v3 o v2.6: resoluciones y precios de lista

Ambos modelos se facturan por segundo de resultado, según la tarifa de la resolución solicitada. Estos son los precios de lista oficiales publicados en la ficha de cada modelo (su tarifa real depende de su grupo y aparece en el catálogo de modelos tras iniciar sesión):

Modelo	720p	1080p	2K	4K
`kling-v3-motion-control`	$0.1324 / s	$0.1765 / s	$0.2647 / s	$0.3971 / s
`kling-v2-6-motion-control`	$0.0735 / s	$0.1176 / s	—	—

Como ejemplo, un clip de 10 segundos en 1080p con kling-v3-motion-control cuesta 10 × $0.1765 = unos $1.77 a precio de lista. La página de precios muestra el mismo nivel 1080p en CNY (¥1.20 por segundo). Use v2.6 para borradores y trabajo de alto volumen en 720p, y v3 cuando necesite 2K o 4K. Los precios de cada nivel están en las fichas de kling-v3-motion-control y kling-v2-6-motion-control.

Paso 1: enviar la tarea

La solicitud va al mismo endpoint que el resto de video de Kling. El escenario determina la función de cada entrada, por lo que la imagen no lleva el campo usage y el video no lleva reference_type:

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "prompt": "Copy the dance moves from the video",
    "resolution": "1080p",
    "images": [{ "url": "https://cdn.example.com/character.png" }],
    "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
    "extra": { "character_orientation": "video" }
  }'

Campo por campo:

images: exactamente un elemento, la persona que ejecutará el movimiento.
videos: exactamente un elemento, la fuente del movimiento. keep_original_sound: true conserva la pista de audio del video original. El control de movimiento no genera audio nuevo.
extra.character_orientation: opcional, image o video. Los dos valores difieren sobre todo en el comportamiento de la cámara y en la duración de entrada admitida. En nuestra prueba, con la misma imagen de persona y el mismo clip de movimiento que incluía un giro de 180°, el personaje se dio la vuelta y mostró la espalda en ambos modos. image conserva el encuadre y la posición de cámara de su imagen de persona, con un fondo casi estático, y acepta videos de movimiento de hasta 10 segundos. video permite que la cámara se reencuadre y se mueva siguiendo el video de movimiento, y acepta videos de hasta 30 segundos. Si lo omite, HopBase envía video. Es la única clave de extra aceptada para el control de movimiento; cualquier otra devuelve 400.
resolution: 720p / 1080p / 2k / 4k en v3, 720p / 1080p en v2.6. También selecciona el nivel de facturación.
duration: no lo envíe. La duración proviene del video de entrada, y enviarlo devuelve duration of model ... is determined by the input media; do not pass duration.

Cada elemento multimedia lleva exactamente uno de url o file_id. Una url debe ser una dirección http(s) absoluta y accesible públicamente. Las rutas relativas, file://, las IP privadas o de loopback y las URL con credenciales incrustadas se rechazan al enviar. Un envío correcto devuelve 202 con un ID de tarea como kt57x….

Paso 2: consultar hasta que la tarea termine

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

El estado pasa de queued a processing y termina en completed o failed. Solo estos dos últimos son finales, así que cualquier otro estado debe tratarse como en curso. Una tarea completada tiene este aspecto:

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "...", "billed_seconds": 10, "cost": 12.0, "cost_usd": 1.765, "currency": "CNY" }
}

outputs es un enlace firmado en api.hop-base.com válido durante 24 horas desde la finalización. Volver a consultar no lo prolonga, así que descargue el archivo a su propio almacenamiento de inmediato. usage.cost_usd es el importe realmente descontado por esta tarea. Un bucle mínimo en Python:

import time, requests

API = "https://api.hop-base.com/v1"
H = {"Authorization": "Bearer sk-YOUR_KEY"}

task = requests.post(f"{API}/video/generate", headers=H, json={
    "model": "kling-v3-motion-control",
    "prompt": "Copy the dance moves from the video",
    "resolution": "1080p",
    "images": [{"url": "https://cdn.example.com/character.png"}],
    "videos": [{"url": "https://cdn.example.com/dance.mp4"}],
    "extra": {"character_orientation": "video"},
}).json()

while True:
    t = requests.get(f"{API}/video/tasks/{task['id']}", headers=H).json()
    if t["status"] == "completed":
        print(t["outputs"][0]); break
    if t["status"] == "failed":
        raise RuntimeError(f"{t['error'].get('code')}: {t['error']['message']}")
    time.sleep(5)

El contrato de solicitud de Kling no incluye un campo de webhook, por lo que la consulta periódica es la única forma de seguir una tarea. Una tarea que siga sin terminar 2 horas después de su creación se marca como fallida con error.code timeout y no se factura. Las tareas no se pueden cancelar.

El video de movimiento: el paso que más falla

HopBase comprueba la estructura de la solicitud al enviarla: cantidades, nombres de campo, forma de las URL y resolución. Kling comprueba el contenido multimedia en sí (formato, tamaño, resolución, duración y contenido) mientras se ejecuta la tarea. Un video que no cumple los requisitos se acepta y luego falla unos minutos después. El caso más común en el control de movimiento:

error.code: reference_input_invalid
the motion reference video was rejected: no complete human upper body was detected in it;
use a video in which a real person's upper body (head to waist) is clearly visible, then submit again

Reglas prácticas para el video de movimiento:

Use una persona real. Se rechazan animales, criaturas y personajes no humanos.
Mantenga la zona de la cabeza a la cintura dentro del encuadre y sin obstrucciones durante todo el clip. Los encuadres muy cerrados, las mesas u objetos delante del torso y el desenfoque de movimiento intenso causan problemas.
Alójelo en un servicio que entregue archivos de forma fiable a clientes de centros de datos. Su propio almacenamiento de objetos o CDN es más seguro que los servicios gratuitos de alojamiento de archivos que bloquean IP de servidores.
Recuerde que la duración del clip es la duración del resultado y, por tanto, determina el costo. Recorte el video antes de enviarlo.
Tenga en cuenta los límites de duración: el video de movimiento puede durar como máximo 10 segundos con character_orientation: image y como máximo 30 segundos con video (el valor predeterminado). Un clip más largo falla aproximadamente medio minuto después del envío con error.code invalid_request y no se factura. En nuestras pruebas, un clip de 12 segundos fue rechazado en modo image y produjo un resultado completo de 12 segundos en modo video; un clip de 31 segundos también fue rechazado en modo video.
La relación de aspecto del resultado sigue a la imagen de persona, no al video de movimiento. Un video de movimiento vertical 9:16 combinado con una imagen de persona de aproximadamente 5:6 produjo un resultado de 864×1040, así que use una imagen de persona vertical si quiere un resultado vertical. En modo image el resultado puede ser ligeramente más corto que el clip: un clip de 5 segundos produjo 4.8 segundos y se facturó como 4 segundos.

Las tareas fallidas nunca se facturan, así que un video rechazado solo le cuesta tiempo.

Errores al enviar

Un error de envío no crea ninguna tarea y no tiene costo. Los específicos del control de movimiento, con sus mensajes exactos:

Lo que envió	`error.message`
Cero o dos imágenes, o ningún video	`motion control requires exactly 1 motion video and 1 character image`
`usage` en la imagen	`motion control images[0] does not accept usage; the character image role is fixed by the scene`
`reference_type` en el video	`motion control videos[0] does not accept reference_type; the motion video role is fixed by the scene`
Cualquier valor de orientación distinto de image/video	`extra.character_orientation must be image or video`
`duration`	`duration of model kling-v3-motion-control is determined by the input media; do not pass duration`
Un campo de la API de OpenAI como `size`	`request body does not match the JSON contract: json: unknown field "size"`

Un 402 con code insufficient_balance significa que su saldo disponible, menos el costo estimado de las tareas que ya están en ejecución, no alcanza para cubrir esta. La retención se libera cuando termina una tarea. El catálogo completo de errores está en la documentación de la API de video de Kling.

Integrarlo en un pipeline

Una configuración típica de producción graba un clip de movimiento limpio para cada acción, como la presentación de un producto, un saludo o un paso de baile. Después se ejecuta ese clip con muchas imágenes de personajes: distintos modelos, atuendos o personajes de marca. Cada ejecución cuesta la duración del clip por la tarifa por segundo, así que el costo es predecible. La misma API key también puede ejecutar texto a video de Kling, texto a voz de MiniMax para la locución y los modelos de chat que escriben sus prompts, siempre que sus grupos incluyan esos modelos. Ejecute GET /v1/models para confirmar a qué puede acceder una clave.

Preguntas frecuentes

¿Puedo fijar la duración de un video de control de movimiento?

No. duration debe omitirse, y enviarlo devuelve 400. El resultado dura lo mismo que el video de movimiento que proporcione, así que recorte el clip original para controlar la duración y el costo.

¿Cuánto puede durar el video de movimiento?

Depende de extra.character_orientation: hasta 10 segundos con image y hasta 30 segundos con video (el valor predeterminado). Un clip más largo falla aproximadamente medio minuto después de iniciar la tarea con invalid_request y no se factura. Para un resultado más largo, divida el movimiento en varios clips, procese cada uno y únalos.

¿Debo usar image o video en character_orientation?

El personaje sigue los giros del video de movimiento en ambos modos. Use image cuando quiera conservar la posición de cámara y el encuadre de su imagen de persona, por ejemplo en una toma fija de producto, y mantenga el clip dentro de 10 segundos. Use video cuando también quiera copiar el movimiento de cámara o cuando el clip dure más de 10 segundos.

¿El control de movimiento genera audio?

No se genera audio nuevo. Para conservar la banda sonora de su video de movimiento, establezca videos[0].keep_original_sound en true. No lo ponga en extra, porque extra.keep_original_sound se rechaza.

¿Por qué falló mi tarea unos minutos después de ser aceptada?

Kling valida el contenido multimedia durante la tarea, no al enviarla. La causa más común es un video de movimiento sin un torso humano real claramente visible (reference_input_invalid). Otras causas son URL ilegibles y la moderación de contenido (input_sensitive). Las tareas fallidas no se facturan.

¿Qué diferencia hay entre kling-v3-motion-control y kling-v2-6-motion-control?

v3 admite 720p, 1080p, 2K y 4K. v2.6 admite 720p y 1080p con un precio de lista por segundo más bajo ($0.0735 / s en 720p y $0.1176 / s en 1080p, frente a $0.1324 / s y $0.1765 / s en v3). El formato de solicitud es el mismo en ambos.

¿Durante cuánto tiempo puedo descargar el resultado?

24 horas desde el momento en que se completa la tarea. Volver a consultar devuelve el mismo enlace sin prolongarlo, y un enlace caducado devuelve 410.

¿Cómo obtengo acceso?

Cree una API key en la consola de HopBase con un grupo que incluya los modelos Kling. Luego ejecute GET /v1/models para confirmar que aparece kling-v3-motion-control. Para los precios de lista, consulte la página de precios.