Cómo usar la API de hiapi para edición de video con IA mediante flux-3

Aquí "edición" tiene un significado concreto: flux-3 (FLUX.3 Video, de Black Forest Labs) extiende un clip existente —continuando su movimiento, el movimiento de cámara y el sonido para generar imágenes nuevas— o construye una toma a partir de un conjunto ordenado de imágenes clave. No recorta, corta, aplica máscaras, ajusta el color ni realiza ningún otro procesamiento in situ sobre el material existente. Si has llegado aquí buscando un editor de clips, las preguntas frecuentes que aparecen más abajo son la forma más rápida de determinar, antes de escribir código, si flux-3 encaja realmente contigo.

Lo que de verdad se le da bien: tomar un video que ya tienes y generar una continuación que mantiene el mismo sujeto, el mismo lenguaje de cámara y el mismo audio —útil para alargar una toma que termina demasiado pronto o para encadenar varios clips generados en una toma más larga. El otro modo recibe un conjunto de imágenes estáticas como imágenes clave ordenadas y genera el movimiento entre ellas, lo que equivale a una edición basada en un guion gráfico, aunque sin ningún video existente de por medio.

1. Qué necesitas

Una clave de API de hiapi del panel de control (sk-...). flux-3, como todos los demás modelos de hiapi, se invoca a través de la API de tareas unificada, así que aquí no hay ninguna configuración específica del modelo: si ya has llamado antes a cualquier otro modelo de video de hiapi, ya tienes todo lo necesario.

2. Ejemplo mínimo funcional

Crea una tarea y luego sondea su estado (o usa una callback; consulta patrones de producción) hasta que alcance un estado terminal.

# 1. Crear tarea — modo de continuación (start_video)
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "Continúa el paneo, la cámara sigue desplazándose hacia la derecha, mantén la misma iluminación",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Sondear hasta el estado 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": "..."}]}}

start_video es una URL HTTPS pública que apunta a un MP4 (el material de origen tiene un límite de 50 MB y 15 segundos): ese es el clip que flux-3 continúa. duration es un entero de 5 a 20 segundos y controla la duración del fragmento nuevo generado, no la del resultado combinado. resolution es 720p o 1080p; aspect_ratio acepta auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 o 9:16. generate_audio es un valor booleano: cuando es true, el sonido ambiente que genera el modelo se incorpora directamente al MP4 de salida en lugar de entregarse como un archivo de audio independiente. Establece draft: true mientras iteras sobre el prompt; las tareas en borrador son más baratas, pero obligan a que resolution sea únicamente 720p (las solicitudes con draft: true y resolution: "1080p" a la vez se rechazan).

Guion gráfico por imágenes clave (no es editar material existente)

El otro modo de entrada usa image_urls en lugar de start_video: un array ordenado de 1 a 10 URL de imágenes que flux-3 trata como un guion gráfico y a partir del cual genera el movimiento que las conecta en orden:

{
  "model": "flux-3",
  "input": {
    "prompt": "Haz un travelling suave que recorra cada escena en orden",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls y start_video son dos formas de tarea distintas sobre el mismo modelo: no envíes ambas en una misma solicitud. Usa image_urls cuando construyas una toma desde cero a partir de imágenes estáticas; usa start_video cuando ya tengas material generado (o de origen) que quieras continuar hacia adelante.

3. Patrones de producción

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

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" se dispara una sola vez, cuando la tarea alcanza cualquier estado terminal: tanto succeeded como failed son estados terminales, así que deduplica tu manejador de webhook por taskId en lugar de asumir que una callback significa éxito. El sondeo con GET /v1/tasks/:id es más adecuado para depuración local, tareas puntuales de baja frecuencia, o como respaldo de reconciliación cuando una callback no llega.

Idempotencia. Si no tienes cuidado, los reintentos tras un tiempo de espera agotado o una conexión interrumpida pueden crear tareas duplicadas (y facturables): guarda el id de la tarea que devuelve la llamada de creación y, antes de plantearte enviar una tarea nueva, convierte el reintento en un GET sobre ese id.

Las URL de salida caducan. El campo expireAt de cada entrada de salida no es decorativo: tanto si te enteras del éxito por callback como por sondeo, descarga el video en cuanto la tarea tenga éxito y guárdalo de forma persistente en tu propio almacenamiento.

Fallos de autenticación. Una clave incorrecta o ausente devuelve HTTP 401 con el contenido {"error": {"code": "permission_denied", ...}}. Comprueba explícitamente ese estado y ese código en lugar de asumir que cualquier respuesta no 2xx significa que la generación en sí ha fallado: "mi clave está mal" y "el modelo ha rechazado mi entrada" requieren soluciones distintas.

Valida las URL de los medios antes de enviar. start_video e image_urls comprueban el tipo y el formato, pero no verifican si el archivo de esa URL existe realmente o si se puede decodificar: una URL sintácticamente válida pero rota sigue creando una tarea, que falla a los pocos segundos en lugar de rechazarse en el momento del envío. Antes de conectar URL a tareas por lotes, confirma que realmente se resuelven.

4. Páginas relacionadas

• Página del modelo flux-3: referencia completa de parámetros, área de pruebas y los precios actuales por segundo y por resolución de los tres modos (texto a video, guion gráfico por imágenes clave y continuación).
• Documentación de creación de tareas: referencia completa de solicitud/respuesta de /v1/tasks, incluidas las opciones de callback.
• Documentación de autenticación: cómo funcionan la cabecera Authorization: Bearer sk-... y los ámbitos de las claves.
• Control de primer y último fotograma en video con IA: un enfoque relacionado para modelos que interpolan entre dos imágenes estáticas, útil si el modo de guion gráfico con múltiples imágenes clave de flux-3 no es lo bastante preciso para tu toma.
• Precios de hiapi: tarifas actuales (la continuación cuesta más que la generación estándar y el modo borrador es más barato que ambos; consulta la página en vivo en lugar de cifras codificadas a mano).

5. Preguntas frecuentes

¿Puede flux-3 recortar, cortar, aplicar máscaras o ajustar el color de un video existente? No. El modo "video a video" de flux-3 es continuación: genera imágenes nuevas que continúan el sujeto, el movimiento de cámara y el sonido del clip de origen. No modifica los fotogramas que ya existen. Actualmente ningún modelo de hiapi realiza ediciones de línea de tiempo (recorte/corte) ni ediciones de región con máscara sobre un video.

¿Cuál es la diferencia entre continuación y guion gráfico por imágenes clave? La continuación (start_video) necesita un archivo de video existente y lo extiende. El guion gráfico por imágenes clave (image_urls) solo necesita imágenes estáticas y genera el movimiento entre ellas: no requiere ningún video de origen. Son entradas mutuamente excluyentes del mismo id de modelo flux-3.

¿Puedo usar start_video e image_urls en la misma solicitud? No: cada tarea elige un modo. Enviar ambos no es una forma de entrada admitida.

¿Está disponible draft: true en el modo de continuación? Sí, y es la forma más económica de iterar sobre el prompt de continuación antes de lanzar una ejecución a resolución completa; pero, igual que en el modo estándar, la continuación en borrador también está limitada a 720p.

¿Por qué mi tarea falla casi al instante en lugar de tardar el tiempo de generación habitual? La causa más frecuente es que la entrada de start_video o de image_urls no se resuelve realmente a un archivo válido en el momento de la solicitud: la API acepta URL con formato sintáctico correcto sin obtenerlas de forma sincrónica, así que un enlace roto se manifiesta como un estado failed rápido en lugar de como un error de validación previo.

¿Cuánto puede durar el clip de origen en el modo de continuación? Como máximo 15 segundos y 50 MB, en formato MP4. Los archivos de origen más largos o más pesados no se aceptan como entrada de start_video.