Control de primer y último fotograma en video con IA: guía de movimiento preciso entre modelos en hiapi

La mayoría de las API de imagen a video solo reciben una imagen estática y luego improvisan el movimiento. Solo unos pocos modelos te permiten fijar el punto final del plano, no solo el inicial: proporcionas el primer fotograma y el último, y el modelo interpola el movimiento entre ambos. Esa es exactamente la diferencia entre "hacer que esta foto se mueva" y "lograr con precisión esta transición".

El problema es que el soporte del control del último fotograma no es uniforme entre modelos, e incluso dentro de la misma línea de productos de un fabricante, la gama insignia y las versiones rápida/turbo pueden diferir. Este tutorial aclara qué modelos de video de hiapi solo admiten control del primer fotograma y cuáles admiten control de primer + último fotograma, y proporciona los campos de entrada reales (y no unificados) de cada uno, para que no descubras tras dar muchas vueltas que el modelo elegido ignoró silenciosamente tu último fotograma.

1. Qué necesitas preparar

Una API key de hiapi de la consola (sk-...) y dos URL de imágenes que el modelo de destino pueda recuperar (URL HTTPS públicas: el endpoint de tareas no admite la carga de archivos locales). Cada uno de los siguientes modelos se invoca mediante la misma API de tareas unificada, así que si tu key funciona para uno de ellos, funcionará para todos.

2. Ejemplo mínimo funcional

Toda la generación de video de hiapi usa el mismo endpoint: crea la tarea y luego sondea su estado (o usa un callback; consulta patrones de producción) hasta que alcance un estado terminal.

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video es el ejemplo más típico de este patrón: input.image_urls acepta una o dos URL de imagen. Si pasas una, el modelo solo ancla el primer fotograma y el resto queda libre; si pasas dos, la segunda URL se convierte en el último fotograma obligatorio: se le indica al modelo dónde debe terminar el plano. La duración es un entero de 3 a 15 (segundos), resolution es 720p / 1080p / 4k, y el booleano opcional sound añade audio ambiente generado. Aquí no hay campo aspect_ratio: la relación de aspecto de salida sigue los fotogramas que proporciones.

No todos los modelos tienen esta estructura. seedance-2.5/image-to-video logra el mismo efecto mediante dos campos con nombres separados en lugar de un array:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url solo tiene sentido cuando se combina con first_frame_url: puedes enviar solo first_frame_url para un plano con solo fotograma inicial, pero no al revés. La duración de este modelo va de 4 a 30 s, la resolución máxima es solo 720p/1080p (sin opción 4K), y aspect_ratio toma por defecto adaptive, es decir, sigue el primer fotograma en lugar de tomar un valor explícito 16:9/9:16.

Los nombres de los campos difieren realmente entre modelos —image_urls frente a first_frame_url/last_frame_url—, así que cada cambio de modelo debe tratarse como un cambio de esquema, no como un reemplazo directo.

No todos los modelos lo admiten

veo-3.1/image-to-video recibe un único string image_url y no tiene ningún parámetro de último fotograma: puedes establecer aspect_ratio (auto/16:9/9:16), resolution y una enumeración fija de duration (4, 6 u 8 segundos), pero no puedes fijar el fotograma final. Lo mismo ocurre con el escalón inferior de la línea Kling: kling-3.0-turbo/image-to-video (la versión rápida/económica de kling-3.0-omni) solo acepta como máximo un elemento en image_urls: sin último fotograma y sin resolución 4K. Si necesitas control del último fotograma, elige la gama insignia o un modelo creado específicamente para ello (como seedance-2.5), en lugar de darlo por hecho basándote en el nombre de la familia del modelo.

3. Patrones de producción

En escenarios a escala, usa callbacks en lugar de sondeo. Pasa un objeto callback en el mismo cuerpo de la solicitud, en lugar de sondear en un bucle:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" se activa una sola vez, cuando la tarea alcanza cualquiera de los estados terminales: tanto succeeded como failed son terminales, así que tu manejador de webhook debe deduplicar por taskId en lugar de suponer que el callback solo representa éxito. El sondeo con GET /v1/tasks/:id es más adecuado para depuración local, llamadas puntuales de baja frecuencia o como red de seguridad de conciliación cuando el callback nunca llega (inestabilidad de red, tu endpoint estuvo temporalmente caído).

Idempotencia. Un reintento tras un timeout o una conexión interrumpida puede crear tareas duplicadas si no se maneja con cuidado: registra el id de la tarea devuelto por la llamada de creación y, antes de considerar enviar una nueva tarea, ejecuta un GET sobre ese id como reintento.

Las URL de salida caducan. El campo expireAt de cada entrada de salida no es decorativo: tanto si te enteras del éxito de la tarea mediante callback como mediante sondeo, descarga el video y persístelo (guárdalo en tu propio almacenamiento) cuanto antes.

Fallos de autenticación. Una key incorrecta o ausente devuelve HTTP 401 y {"error": {"code": "permission_denied", ...}}. Comprueba explícitamente ese estado/código de error en lugar de suponer que cualquier respuesta no 2xx significa que la generación en sí falló: en el manejo de errores vale la pena distinguir entre "mi key está mal" y "el modelo rechazó mi entrada", porque las soluciones son completamente distintas.

4. Páginas relacionadas

• Página del modelo Kling 3.0 Omni de imagen a video —— precios, prueba en línea y referencia completa de parámetros del modelo usado en los ejemplos anteriores.
• Página del modelo Seedance 2.5 de imagen a video —— la variante con first_frame_url/last_frame_url.
• Documentación de autenticación —— cómo funcionan la cabecera Authorization: Bearer sk-... y el ámbito de las keys.
• Documentación de creación de tareas —— referencia completa de solicitud/respuesta de /v1/tasks, incluidas las opciones de callback.
• Precios de hiapi —— precios actuales por segundo y por resolución (la facturación varía según el modelo y la resolución; consulta la página en vivo en lugar de cifras fijas).

5. Preguntas frecuentes

¿Qué modelos de video de hiapi admiten control del último fotograma? kling-3.0-omni/image-to-video (mediante un array image_urls con 2 elementos) y seedance-2.5/image-to-video (mediante first_frame_url + last_frame_url) lo admiten actualmente. veo-3.1/image-to-video y kling-3.0-turbo/image-to-video no lo admiten: solo aceptan un único fotograma inicial.

¿Se puede especificar solo el último fotograma sin proporcionar un prompt? Ambos modelos siguen aceptando (y normalmente esperan) un prompt además de los fotogramas: guía el movimiento entre los dos fotogramas, no solo el contenido. No todos los modelos rechazan directamente un prompt vacío o ausente, pero describir explícitamente la transición hace que el movimiento sea más predecible.

¿Los dos fotogramas deben tener la misma relación de aspecto? Ni kling-3.0-omni/image-to-video ni seedance-2.5/image-to-video ofrecen un aspect_ratio explícito independiente de la configuración de las imágenes: la relación de aspecto de salida sigue los fotogramas de entrada, así que relaciones de aspecto incoherentes entre el primer y el último fotograma producen resultados visiblemente incómodos en lugar de un error. Antes de enviar, recorta o rellena ambos fotogramas a la misma proporción.

¿Qué ocurre si solo envías el último fotograma y no el primero? Ninguno de los dos modelos lo admite: en seedance-2.5, last_frame_url solo puede usarse junto con first_frame_url; el array de kling-3.0-omni se lee por posición (el primer elemento = primer fotograma). No existe un modo "inverso" en el que solo se especifique el fotograma final.

¿El control del último fotograma equivale a la transferencia de movimiento de video a video? No es equivalente: esa es otra capacidad (seedance-2.5/reference-to-video en hiapi, que recibe un video de referencia para impulsar el movimiento o el movimiento de cámara, en lugar de dos imágenes estáticas). El control de primer/último fotograma interpola entre dos imágenes; la referencia de video a video imita el patrón de movimiento de un clip existente.

¿Añadir el último fotograma es más caro que generar solo con el primero? Ambos modelos facturan por segundo y por resolución, no por imagen de entrada, así que añadir el último fotograma no aumenta el coste por sí mismo: consulta la página de precios para conocer las tarifas actuales.