Cómo llamar a flux-3-max/keyframes-to-video mediante la API de HiAPI: guía de curl y Python

Qué hace realmente esta integración

flux-3-max/keyframes-to-video es una API de tareas asíncrona que genera videos a partir de imágenes de fotogramas clave. A diferencia de los endpoints síncronos, que devuelven el resultado en la misma respuesta HTTP, este modelo recibe tus fotogramas clave, crea una tarea en segundo plano y devuelve un identificador de tarea que puedes usar para comprobar el progreso.

El ciclo de vida completo consta de cuatro fases:

1. Autenticación: cada solicitud lleva tu clave de API de HiAPI.
2. Envío: se envían los fotogramas clave y los parámetros para iniciar la tarea de video.
3. Sondeo: se consulta repetidamente el estado de la tarea hasta alcanzar un estado terminal.
4. Obtención: se descarga el video generado desde la URL que devuelve la tarea cuando finaliza con éxito.

Tener presente este ciclo de vida determina cómo escribir tu cliente: el envío y la obtención del resultado son llamadas separadas, y tu aplicación debe tolerar una tarea que puede tardar desde decenas de segundos hasta varios minutos. Los ejemplos de curl y Python que siguen recorren las mismas cuatro fases, de modo que puedes trasladar este flujo a cualquier lenguaje o ejecutor de trabajos.

Obtener una clave de API y autenticarse

Tu clave de API se emite desde el panel de HiAPI. Trátala como una contraseña: identifica tu cuenta y autoriza llamadas facturables, por lo que nunca debe aparecer en el código fuente, el historial de confirmaciones ni la salida de registros.

La autenticación se transmite en cada solicitud como una cabecera HTTP:

Authorization: Bearer $HIAPI_API_KEY

En la práctica, guarda la clave en una variable de entorno y léela en tiempo de ejecución. Para los ejemplos de shell, expórtala una vez por sesión:

export HIAPI_API_KEY="your-key-here"

En Python, léela con os.environ["HIAPI_API_KEY"] en lugar de codificar la cadena directamente. Añade el archivo .env a .gitignore y, si registras solicitudes para depuración, oculta la cabecera Authorization antes de que llegue al agregador de registros. Si la clave se ha expuesto alguna vez, rótala de inmediato desde el panel.

Construir la solicitud con curl

Enviar una tarea de video implica enviar un cuerpo JSON que especifica el modelo y contiene tus fotogramas clave. Los nombres exactos de los campos de entrada de fotogramas clave y de los parámetros de generación están documentados en la página del modelo, así que úsala como fuente autoritativa; la estructura siguiente muestra la forma de la solicitud.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/keyframes-to-video",
    "input": {
      "keyframes": [
        "https://example.com/frame-01.png",
        "https://example.com/frame-02.png"
      ]
    }
  }'

Función de cada parte:

• model: selecciona flux-3-max/keyframes-to-video, de modo que el mismo endpoint pueda enrutarse más adelante a otros modelos sin cambiar tu código de transporte.
• input.keyframes: lista ordenada de URL de imágenes. El orden importa: el primer fotograma ancla el inicio del clip y los siguientes guían los momentos posteriores.
• Authorization: la cabecera bearer descrita anteriormente.
• Content-Type: necesaria para el cuerpo JSON.

La respuesta es un objeto de tarea que contiene un identificador. Guarda ese ID; es el identificador que usarás en cada sondeo posterior.

La misma solicitud en Python

La versión en Python replica la llamada de curl. Usar requests permite mantenerla breve, pero la biblioteca estándar también sirve si prefieres cero dependencias.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"


def submit_video_task(keyframe_urls: list[str]) -> str:
    response = requests.post(
        f"{BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "flux-3-max/keyframes-to-video",
            "input": {"keyframes": keyframe_urls},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


task_id = submit_video_task([
    "https://example.com/frame-01.png",
    "https://example.com/frame-02.png",
])
print(task_id)

Hay dos detalles que conviene mantener: el timeout explícito, para que una conexión colgada no bloquee tu proceso de trabajo indefinidamente, y raise_for_status(), para que un 4xx o 5xx surja como excepción en lugar de como una carga de error silenciosa. Mantén la función pequeña y pura: debe enviar y devolver el ID, nada más. El sondeo es otra cuestión.

Sondear el estado de la tarea y obtener el resultado

La generación de video requiere tiempo de cómputo real, por lo que la API no se bloquea hasta que el archivo aparezca. En su lugar, consultas la tarea hasta que finaliza. El estado succeeded incluye la URL de salida; failed incluye el error; cualquier otro valor significa que debes seguir esperando.

import time
import requests


def wait_for_video(task_id: str, poll_interval: int = 5, max_wait: int = 600) -> str:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "succeeded":
            return task["output"]["video_url"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(poll_interval)

    raise TimeoutError(f"task {task_id} did not finish in time")

Notas de diseño para producción:

• Intervalo de sondeo: unos pocos segundos son suficientes. Martillear el endpoint aumenta la carga sin hacer que la tarea termine antes.
• Fecha límite: limita siempre el tiempo total de espera y falla de forma ruidosa en caso de error, en lugar de repetir indefinidamente.
• Descarga: la URL devuelta es temporal; obtén el archivo inmediatamente después de que la tarea finalice con éxito y muévelo a tu propio almacenamiento.
• Desacoplamiento: en una aplicación web, ejecuta este bucle en un proceso de trabajo en segundo plano y notifica al cliente mediante webhook o cola, en lugar de mantener abierta la solicitud HTTP.

Gestionar errores y casos límite

La mayoría de los fallos de integración se agrupan en cuatro categorías.

Errores de autenticación (401/403). La clave falta, tiene un formato incorrecto o ya no es válida. Comprueba que la variable de entorno esté realmente exportada en el proceso que realiza la llamada; una trampa habitual es que el shell local funcione, pero la variable falte en el contenedor o en el trabajo de cron.

Errores de entrada (4xx). Una URL de fotograma clave inaccesible, un formato de imagen no compatible o parámetros fuera del rango permitido harán que se rechace el envío. Verifica antes de enviar que cada URL de fotograma clave sea accesible públicamente; los hosts lentos o restringidos son la causa más común de que falle una solicitud que por lo demás era correcta.

Fallo de la tarea. Una tarea puede aceptarse y luego fallar durante la generación. Comprueba siempre el campo de error en lugar de dar por exitoso un sondeo completado. Registra el ID de la tarea junto con el error para poder relacionarlo con una solicitud de soporte.

Tiempos de espera y reintentos. Los errores de red al enviar suelen poder reintentarse de forma segura con retroceso exponencial. Reintentar después de un envío correcto no es seguro: podrías crear tareas duplicadas y generar cargos duplicados. Lee la respuesta antes de reintentar y usa también retroceso exponencial con jitter en el bucle de sondeo.

Una última recomendación de higiene: nunca registres la cabecera Authorization y, si las URL de los fotogramas clave contienen cadenas de consulta firmadas, sanea esas cadenas. Si tienes dudas sobre los nombres de campo o los límites de este modelo, consulta la documentación de flux-3-max/keyframes-to-video y replica fielmente esos valores en tu cliente.