Guía rápida de la API de control de movimiento de Kling V3.0

El control de movimiento de Kling V3.0 permite animar una imagen estática de un personaje extrayendo el movimiento de un video de referencia y aplicándolo fotograma a fotograma. El resultado conserva la apariencia del personaje de tu imagen mientras reproduce el movimiento del video: una técnica llamada transferencia de movimiento. Esta guía cubre el endpoint de Novita AI, las entradas requeridas, los parámetros clave y ejemplos funcionales en Python y curl que puedes ejecutar con una clave de API real.

Cuándo usar el control de movimiento

El control de movimiento es la herramienta adecuada cuando tienes dos cosas: una imagen estática de un personaje que quieres animar y un video de referencia cuyo movimiento deseas reproducir. Es diferente de la funcionalidad de Imagen a Video (I2V), que genera movimiento a partir de un prompt. Con el control de movimiento, el movimiento se copia del video de referencia con precisión: el personaje resultante seguirá el mismo arco de movimiento que la persona en el video de referencia.

Úsalo cuando:

• Quieras aplicar un baile, ciclo de caminata o gesto específico a una ilustración o foto de un personaje.
• Necesites un movimiento consistente y repetible en diferentes personajes (mismo video de referencia, diferentes imágenes).
• Estés creando contenido donde la calidad del movimiento importe y los resultados abiertos de I2V con prompt sean demasiado impredecibles.

No lo uses cuando el movimiento en sí mismo aún no esté definido; en ese caso, I2V con un prompt descriptivo te da más flexibilidad a un costo menor.

Paso 1: Obtén tu clave de API de Novita

Regístrate en novita.ai y genera una clave de API desde el panel. Las cuentas nuevas reciben créditos gratuitos que puedes usar para probar el control de movimiento antes de comprometerte con un volumen de producción.

Paso 2: Confirma el endpoint y el ID del modelo

El control de movimiento de Kling V3.0 en Novita AI sigue el patrón de video asíncrono estándar:

Enviar tarea:

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

Consultar resultado:

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

Todas las solicitudes requieren:

Authorization: Bearer TU_CLAVE_API_NOVITA
Content-Type: application/json

Documentación completa: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

Paso 3: Prepara tus entradas

El control de movimiento requiere dos entradas: una imagen de referencia y un video de referencia. Conseguir estos elementos correctamente es el factor más importante para la calidad del resultado.

Imagen de referencia

Este es el personaje cuya apariencia conservará el resultado. Requisitos:

• Formatos: JPEG, PNG, JPG
• Tamaño máximo: 10 MB
• Resolución mínima: 340px en cada lado
• Relación de aspecto: entre 2:5 y 5:2
• El personaje debe ser claramente visible, ocupar más del 5% del área de la imagen y no tener una oclusión severa (no recortes la cabeza o el cuerpo)

Para obtener los mejores resultados, usa una imagen donde las proporciones del cuerpo del personaje coincidan aproximadamente con lo que se ve en el video de referencia. Si el video de referencia muestra un bailarín de cuerpo entero, usa una imagen del personaje de cuerpo entero en lugar de un recorte de retrato.

Video de referencia

Esta es la fuente de movimiento. El personaje en el resultado replicará los movimientos de este video:

• Formatos: MP4, MOV
• Tamaño máximo: 10 MB
• Duración: 3–30 segundos
• Resolución mínima: 340px en cada lado
• Relación de aspecto: entre 2:5 y 5:2
• La persona en el video de referencia debe tener su cuerpo completo o parte superior visible y sin obstrucciones, incluida la cabeza

Las tomas claras y bien iluminadas con un fondo limpio transfieren el movimiento con mayor precisión que las tomas ruidosas o concurridas.

Paso 4: Envía tu primera solicitud

Solicitud curl mínima:

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "A person performing a smooth dance routine, cinematic lighting",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

La respuesta devuelve un task_id inmediatamente:

{
  "task_id": "abc123xyz"
}

Paso 5: Consulta el resultado

El control de movimiento de Kling V3.0 es asíncrono. Envía la tarea, luego consulta hasta que el estado sea succeed:

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

Cuando se complete, la respuesta contendrá un array videos con la URL de salida:

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

El tiempo típico de generación es de 30 a 120 segundos dependiendo de la duración del video y el modo. Consulta cada 5–10 segundos en lugar de golpear el endpoint constantemente.

Ejemplo completo de integración en Python

Este script envía una tarea de control de movimiento y consulta hasta que se completa:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(8)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("Submitting task...")
    task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
    print(f"Task ID: {task_id}")

    print("Polling for result...")
    output_url = poll_result(task_id)
    print(f"Output video: {output_url}")

Referencia de parámetros de la API

Parámetro	Tipo	Requerido	Descripción
image	string	Sí	URL de la imagen del personaje a animar. Ver requisitos de entrada más arriba.
video	string	Sí	URL del video de referencia cuyo movimiento se transferirá.
model_name	string	Sí	Establecer en kling-v3.0-motion-control.
prompt	string	No	Descripción textual del estilo de movimiento deseado o contexto de la escena. Opcional pero puede mejorar la calidad del resultado.
character_orientation	string	No	Controla la alineación de la pose y la duración del resultado. "video" coincide con la orientación del video de referencia: mejor para movimientos complejos de cuerpo completo, soporta hasta 30s. "image" coincide con la orientación de la imagen del personaje: mejor para movimientos relativos a la cámara, fijo en 5s.

character_orientation en la práctica

Si tu video de referencia muestra un bailarín de frente y la imagen de tu personaje también está de frente, "video" dará una mejor transferencia de movimiento y soporta hasta 30 segundos. Si el video de referencia tiene una cámara que se mueve alrededor del sujeto y tu imagen es un retrato en ángulo fijo, "image" tiende a reducir la distorsión de perspectiva no deseada, pero ten en cuenta que genera un clip fijo de 5 segundos.

Estándar vs. Pro: qué nivel de calidad elegir

El control de movimiento de Kling V3.0 está disponible en dos niveles de calidad:

Estándar genera a 720p. Es la opción adecuada para iterar, probar la compatibilidad del movimiento o generar borradores antes de comprometerse con una versión final.

Pro genera a 1080p con una fidelidad de movimiento mejorada y consistencia del sujeto. Usa Pro cuando:

• El resultado va a una producción terminada (publicación social, cortometraje, demo de producto).
• Los detalles finos en la cara o la ropa del personaje son importantes.
• Estás generando clips más largos (10s+) donde la degradación de la calidad a lo largo del tiempo es más visible.

Para la mayoría de los flujos de trabajo de desarrollo, comienza con Estándar para confirmar la compatibilidad de entrada y la calidad del movimiento, luego cambia a Pro para la versión final.

Precios, duración y estimaciones de costo

Novita AI factura el control de movimiento por segundo de video generado. Los niveles Estándar y Pro tienen tarifas por segundo separadas. Para conocer los precios actuales, consulta la página del modelo Novita AI.

Límites de duración:

• character_orientation: "video" — hasta 30 segundos
• character_orientation: "image" — fijo en 5 segundos

El costo se escala con la duración en el modo "video". El modo "image" siempre genera un clip de 5 segundos.

Solución de problemas comunes

La tarea falla inmediatamente con un error 422 o de validación Verifica que tanto image como video sean URL accesibles públicamente (no detrás de autenticación o una URL prefirmada de corta duración que haya expirado). El backend de Novita debe poder obtener ambos archivos en el momento de la ejecución de la tarea.

El movimiento resultante se ve incorrecto o el personaje se distorsiona La causa más común es un desajuste entre la orientación del personaje en la imagen y el video de referencia. Intenta cambiar character_orientation entre "video" y "image" para ver cuál produce una mejor alineación.

El personaje pierde la identidad facial a mitad del clip Asegúrate de que el personaje en la imagen de referencia tenga una cara y un cuerpo claros y sin obstrucciones. Para clips más largos, el nivel Pro mantiene mejor la consistencia del sujeto que el Estándar.

El movimiento del video de referencia no se transfiere limpiamente Las tomas de referenia ruidosas o concuridas degradan la extracción del movimiento. Usa tomas donde el intérprete sea el sujeto principal con un fondo razonablemente limpi. Evita tomas temblorsas hechas a mano si el objetivo es una transferencia de movimiento suave.

El estado se queda en processing por más de 3 minutos Ocasionales demoras en la cola ocurren. Espera hasta 5 minutos antes de considerarlo atascado. Si permanece atascado, envía una tarea nueva; no reutilices el task_id anterior.

Qué construyen los desarrolladores con Kling Motion Control

Animación de personajes para activos de juegos: Toma una ilustración de un personaje y aplica un clip de movimiento de referenia (caminar, correr, atacar) sin software de rigging ni animación.

Contenido social con movimiento consisente: Aplica el mismo video de bail de referenia a múltiples imágenes de personajes para producir una serie de clips con coreografía idéntica pero diferentes apariencias.

Previsualización: Prueba cómo se ve una secuencia de movimiento específica en un diseño de personaje antes de invertir en animación de producción completa.

Visualización de productos de comercio electrónico: Aplica cambios sutiles de pose o movimiento de la ropa a imágenes de productos usando un video de referencia cuidadosamente elegido que muestre el movimiento de la prenda.

Preguntas frecuentes

¿Cuál es la diferencia entre Motion Control e Image-to-Video en Novita AI?

Image-to-Video (I2V) anima una imagen basándose en un prompt de texto: el movimiento es generado por el modelo a partir de tu descripción. Motion Control transfiere un movimiento específico de un video de referencia al personaje de tu imagen. Motion Control te da un movimiento preciso y reproducible; I2V te da flexibilidad creativa sin necesiad de un clip de referenia.

¿El personaje del video de referenia debe coincidir con la apariencia de la imagen del personaje?

No. El video de referenia se usa solo para la extracción del movimiento: el personaje resultante proviene de la imagen, no del video. Esa es la capacidad principal: movimiento de una fuente, apariencia de otra. Las proporciones deben coincidir aproximadamente (imagen de cuerpo completo para video de cuerpo completo, retrato para video de parte superior del cuerpo) para una mejor calidad de transferencia.

¿Puedo usar cualquier video públicamente dispnible como referenia?

Puedes usar cualquier video que cumpla con los requisitos de formato y tamaño. El movimiento se transfiere mejor de tomas donde el sujeto es claramente visible con una oclusión mínima. Las escenas complejas con múltiples personas o tomas muy editadas (cortes, zooms) pueden reducir la precisión.

¿Cuánto tiempo toma la generación?

Generalmente de 30 a 120 segundos dependiendo de la duración del resultado y si elegiste el modo Estándar o Pro. Consulta cada 8–10 segundos en lugar de en un bucle cerrado.

Artículos recomendados

• Kling 3.0 ya está en Novita AI: generación de video AI cinematográfica a escala
• Guía rápida de la API de Kling V3.0 4K
• API de Kling V2.5 Turbo en Novita AI