Tutorial
Cómo usar kling-3.0/motion-control a través de la API de HiAPI: ejemplos en curl y Python
En esta página
Para qué sirve kling-3.0/motion-control y cuándo elegirlo
El control de movimiento es un tipo de capacidad dentro de la generación de video: le entregas un video de referencia al modelo y este impulsa el movimiento, el ritmo y la composición de la salida, en lugar de describir la acción únicamente mediante un prompt de texto. Al usar kling-3.0/motion-control en la API de HiAPI, el video de referencia es la entrada principal: ancla cómo se mueven los objetos, mientras que los demás parámetros moldean el contenido generado en torno a ese movimiento.
Cuando el movimiento en sí es la dificultad, conviene elegir este modelo. Escenarios típicos de uso:
- Tienes un video corto y quieres reproducir su movimiento de cámara o la acción del sujeto con contenido diferente.
- Necesitas un movimiento predecible en lugar de un resultado de texto a video que dependa de la suerte del prompt de texto.
- Estás construyendo una canalización en la que el movimiento es un activo reutilizable a lo largo de varias generaciones, por lo que debe ser una entrada y no una descripción en una frase.
Si solo necesitas texto a video y no dispones de una referencia de movimiento, el control de movimiento solo añadirá un paso de carga y restricciones de entrada más estrictas sin beneficio. Del mismo modo, si el video de referencia es muy largo o su composición es inestable, espera más reintentos. El resto de esta guía asume que ya has determinado que el control de movimiento es la herramienta adecuada y que deseas una integración fiable y reproducible.
Requisitos previos y configuración del endpoint
Antes de la primera llamada, prepara tres cosas.
1. Clave de API
Crea una clave en la consola de tu cuenta de HiAPI.ai y guárdala en una variable de entorno en lugar de escribirla en el código fuente:
export HIAPI_API_KEY="your_api_key_here"
Envíala en cada solicitud como token bearer: Authorization: Bearer $HIAPI_API_KEY.
2. Convención de la URL base
Todas las llamadas a HiAPI comparten la misma URL base y un prefijo de ruta con versión. Coloca la URL base en la configuración para que cambiar de entorno no requiera modificar los puntos de llamada:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. Identificador del modelo
El modelo se selecciona por solicitud mediante el campo model del cuerpo de la solicitud y debe usarse el identificador exacto kling-3.0/motion-control. No lo codifiques directamente en varios lugares: pásalo como una constante para que un futuro cambio de modelo solo requiera modificar una línea.
También necesitas una ubicación alojada desde la que la API pueda obtener el video de referencia. Lo habitual es usar una URL firmada con tiempo limitado; asegúrate de que sea accesible sin encabezados personalizados ni cookies.
Con estos tres elementos listos, lo que queda es la estructura de la solicitud y el ciclo de vida de la tarea.
Proporcionar el video de referencia y los parámetros de movimiento
Una solicitud de control de movimiento se divide conceptualmente en dos mitades: la fuente del movimiento (tu video de referencia) y la configuración de generación (qué debe producir el modelo).
Video de referencia
El video de referencia se coloca en el cuerpo de la solicitud como una URL, no se envían bytes sin procesar dentro de la carga JSON. Dos reglas prácticas:
- Usa una URL que siga siendo válida durante todo el tiempo que la tarea esté en cola y en procesamiento. Que una URL firmada caduque antes de tiempo es una causa frecuente de que la tarea falle unos minutos después del envío.
- Mantén el video corto y con imagen estable. Un material de referencia demasiado largo, con mucho temblor o con cortes frecuentes proporciona al modelo una señal de movimiento ambigua.
Si el material está en almacenamiento privado, genera la URL firmada al enviar la tarea con una validez suficientemente larga, en lugar de generarla al subirlo.
Parámetros de movimiento y salida
Parámetros que suelen configurarse junto con el video de referencia:
- Un prompt de texto que describa el contenido objetivo que debe impulsar el movimiento de referencia.
- Ajustes de relación de aspecto y duración de la salida para que el video generado coincida con tu ubicación de presentación.
- Cualquier ajuste de intensidad de movimiento o de fidelidad que exponga el modelo, para sopesar la fidelidad a la referencia frente a la libertad del prompt.
Reúne estos parámetros en un objeto de configuración pequeño y explícito en el cliente, en lugar de dispersarlos entre los argumentos de las funciones. Así resulta fácil registrar exactamente qué se envió, que es el material de depuración más útil con este modelo.
Por último, valida antes de enviar: que la URL de referencia devuelva un tipo de contenido multimedia, que el prompt no esté vacío y que todos los ajustes numéricos estén dentro del rango documentado. Una comprobación local cuesta milisegundos; una tarea asíncrona rechazada cuesta un viaje de ida y vuelta y confusión.
Tarea asíncrona: enviar, sondear y leer el resultado
El control de movimiento no devuelve el video en la respuesta de envío, sino un identificador de tarea que debes seguir. Construye el cliente en torno a ese ciclo de vida desde el principio.
Paso 1 — Enviar
Envía la tarea con POST al endpoint del modelo. Un envío correcto devuelve el identificador de la tarea. Persiste ese ID de inmediato: es tu único identificador para operar con la tarea y se usará tanto en el sondeo como en las solicitudes de soporte.
Paso 2 — Sondear
Obtén el estado de la tarea con GET usando ese ID. El campo de estado te indica en cuál de estas tres situaciones estás:
- Pendiente o en cola: aceptada, aún no iniciada. Sigue esperando.
- Procesando o en ejecución: en curso. Sigue esperando, pero con retroceso exponencial.
- Estado terminal: éxito o fallo. Deja de sondear.
El bucle de sondeo debe comprobar explícitamente los estados terminales, no solo si existe el campo de salida. Una tarea fallida no tiene resultado, y tratar «aún sin resultado» como «sigue en ejecución» provoca un bucle infinito.
Paso 3 — Leer el resultado
En caso de éxito, la respuesta incluye la ubicación de la salida, normalmente la URL del video generado. Descárgalo puntualmente a tu propio almacenamiento: un activo generado detrás de una URL temporal no debe considerarse disponible de forma permanente.
Buenas prácticas de sondeo
Dos reglas lo mantienen fiable en producción:
- Aplica retroceso entre sondeos (empieza con uno o dos segundos y luego auméntalo), en lugar de saturar el endpoint.
- Limita el tiempo total de espera y expón el tiempo de espera agotado como un error reintentable, en lugar de bloquear indefinidamente el hilo de trabajo.
Registra el ID de tarea, los parámetros enviados y el estado final de cada ejecución. Cuando algo vaya mal, ese registro responderá a la mayoría de las preguntas antes de que tengas que preguntar a otros.
Solicitud curl ejecutable
A continuación se muestra el flujo completo en el shell. Envía la tarea, extrae el ID de tarea y luego sondea hasta que la tarea alcance un estado terminal.
#!/usr/bin/env bash
set -euo pipefail
BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"
# 1) Enviar la tarea
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0/motion-control",
"prompt": "un barco de papel flotando por una calle urbana bajo la lluvia, cinematográfico",
"reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
"duration": 5,
"aspect_ratio": "16:9"
}')
echo "$SUBMIT"
TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"
# 2) Sondear hasta el estado terminal
while true; do
STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY")
STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
echo "status: $STATUS"
case "$STATUS" in
succeeded) echo "$STATUS_JSON"; break ;;
failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
esac
sleep 3
done
Dos notas sobre cómo adaptar este script. Primero, guarda el identificador del modelo y la ruta del endpoint en variables para que el script siga siendo legible. Segundo, el análisis anterior no usa jq, solo Python, porque Python está disponible casi en cualquier lugar; si prefieres jq, puedes sustituirlo. En cualquier caso, el comportamiento clave es el mismo: extraer el ID de tarea de la respuesta de envío y luego sondear su estado hasta ver un valor terminal.
La misma solicitud (versión en Python)
El cliente Python siguiente se corresponde con el flujo curl, pero su bucle de sondeo es más robusto: retroceso casi exponencial, tiempo de espera total y manejo explícito de cada estado terminal.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
TERMINAL = {"succeeded", "failed", "cancelled"}
def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
payload = {
"model": MODEL,
"prompt": prompt,
"reference_video_url": reference_video_url,
"duration": duration,
"aspect_ratio": "16:9",
}
r = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
r.raise_for_status()
return r.json()["id"]
def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/videos/generations/{task_id}",
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in TERMINAL:
return data
time.sleep(delay)
delay = min(delay * 1.5, 15.0)
raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task_id = submit_job(
prompt="un barco de papel flotando por una calle urbana bajo la lluvia, cinematográfico",
reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
)
print("submitted:", task_id)
result = wait_for_job(task_id)
if result["status"] == "succeeded":
print("output:", result.get("output"))
else:
print("job did not succeed:", result)
Aspectos que conviene conservar al adaptarlo: el conjunto de estados terminales, el retroceso con límite superior y las funciones separadas de envío y espera. En un servicio real, las separarías en dos procesos —enviar desde el manejador de solicitudes, guardar el ID de tarea y dejar que un worker sondee— para que las tareas lentas nunca bloqueen la respuesta HTTP.
Puntos de fallo habituales y cómo depurarlos
La mayoría de los problemas de integración con kling-3.0/motion-control se agrupan en unas pocas categorías. Compruébalas en orden.
Errores de autenticación y de modelo
Un 401 casi siempre significa que el token bearer falta, está truncado o se tomó del entorno equivocado. Un error de modelo no encontrado significa que la cadena model no coincide exactamente: es un identificador separado por una barra, por lo que un orden de caracteres incorrecto o un espacio adicional fallará silenciosamente en la configuración y ruidosamente en la API.
Video de referencia no disponible
La tarea se acepta y, minutos después, falla porque no se pudo obtener la URL de referencia. Causas ordenadas por frecuencia: la URL firmada caducó antes del procesamiento; la URL requiere un encabezado de autenticación que el servicio no envía; la URL devuelve HTML (una página de inicio de sesión o de error) en lugar de video. Prueba la URL con un curl normal desde fuera de tu red y confirma el tipo de contenido.
Formato de parámetros incorrecto o fuera de rango
Que los ajustes de duración y relación de aspecto estén fuera del rango documentado se rechaza en el envío, lo cual es bueno: obtienes el error de inmediato. Valídalos localmente primero para que una errata no requiera un viaje de ida y vuelta para descubrirse.
Defectos de sondeo
Dos problemas clásicos: un bucle que solo comprueba el campo de salida y nunca failed, lo que provoca un bucle infinito; y sondear en un bucle ajustado sin espera, lo que hace que te limiten la tasa. Añade comprobación explícita de estados terminales y retroceso, y adjunta siempre el ID de tarea en los informes de error para poder consultar la tarea en lugar de reconstruirla.
URL de resultado caducada
Generaste el video, pero solo guardaste la URL de salida temporal. Descarga la salida a tu propio almacenamiento en cuanto la tarea tenga éxito; trata la URL devuelta como un identificador para la descarga, no como almacenamiento persistente.
Al inicio de cada sesión de depuración, registra el cuerpo exacto de la solicitud y el JSON de respuesta sin procesar. Casi todos los problemas anteriores se ven en esos dos materiales. Cuando estés listo para profundizar, consulta otros modelos de video y la referencia de endpoints en la documentación de HiAPI.ai, y mantén la misma forma de cliente de «primero enviar, luego sondear».
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio