Inicio rápido de la API de Control de Movimiento de Kling V3.0

El Control de Movimiento de Kling V3.0 te permite animar una imagen de personaje estático 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 API real.

Cuándo usar Control de Movimiento

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

Úsalo cuando:

• Quieras aplicar un baile, ciclo de marcha o gesto específico a una ilustración o foto de 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 sea importante y los resultados abiertos de I2V con prompts 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 menor costo.

Paso 1: Obtén tu clave API de Novita

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

Paso 2: Confirma el endpoint y el ID del modelo

Kling V3.0 Control de Movimiento en Novita AI utiliza 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_DE_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

Control de Movimiento requiere dos entradas: una imagen de referencia y un video de referencia. Prepararlas correctamente es el factor más importante en 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: 340 px 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 pesada (no recortes la cabeza ni el cuerpo)

Para 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 completo, usa una imagen de personaje de cuerpo completo en lugar de un recorte de retrato.

Video de referencia

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

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

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

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

Kling V3.0 Control de Movimiento 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 contiene 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 de generación típico es de 30 a 120 segundos, dependiendo de la duración del video y el modo. Consulta cada 5 a 10 segundos en lugar de saturar el endpoint.

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. Consulta los requisitos de entrada anteriores.
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 de salida.
character_orientation	string	No	Controla la alineación de la pose y la duración de la salida. "video" coincide con la orientación del video de referencia — mejor para movimientos corporales complejos, 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 tu imagen de 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 de á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

Kling V3.0 Control de Movimiento está disponible en dos niveles de calidad:

Estándar produce salida 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 produce salida a 1080p con una fidelidad de movimiento mejorada y consistencia del sujeto. Usa Pro cuando:

• La salida se destina a una producción final (publicación en redes sociales, cortometraje, demostración de producto)
• Los detalles finos en la cara o la ropa del personaje importan
• Estás generando clips más largos (10s+) donde la degradación de la calidad con el 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 costos

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 de Novita AI.

Límites de duración:

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

El costo escala con la duración para 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 de salida se ve incorrecto o el personaje se distorsiona La causa más común es una discrepancia entre la orientación del personaje en la imagen y el video de referencia. Intenta cambiar character_orientation entre "video" e "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 ruidosas o abarrotadas degradan la extracción del movimiento. Usa tomas donde el intérprete sea el sujeto principal con un fondo razonablemente limpio. Evita las tomas temblorosas hechas a mano si el objetivo es una transferencia de movimiento suave.

El estado se queda en processing durante más de 3 minutos Ocasionalmente, ocurren retrasos en la cola. Espera hasta 5 minutos antes de considerarlo atascado. Si sigue atascado, envía una nueva tarea; no reutilices el task_id antiguo.

Qué construyen los desarrolladores con Kling Control de Movimiento

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

Contenido social con movimiento consistente: Aplica el mismo video de referencia de baile 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 la producción de animació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 utilizando un video de referencia cuidadosamente elegido que muestre el movimiento de la prenda.

Preguntas frecuentes

¿Cuál es la diferencia entre Control de Movimiento e Imagen a Video en Novita AI?

Imagen a 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. Control de Movimiento transfiere un movimiento específico de un video de referencia al personaje de tu imagen. Control de Movimiento te da un movimiento preciso y reproducible; I2V te da flexibilidad creativa sin necesidad de un clip de referencia.

¿Es necesario que el personaje del video de referencia coincida con la apariencia del personaje de la imagen?

No. El video de referencia se utiliza solo para la extracción del movimiento; el personaje de salida 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 disponible públicamente como referencia?

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

¿Cuánto tiempo lleva la generación?

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

Artículos recomendados

• Kling O1 en Novita AI: modos T2V, I2V, Ref2V y edición de video
• Kling 3.0 ya está en Novita AI: generación de video AI cinematográfica a escala
• API de Kling V2.5 Turbo en Novita AI