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

Qué hace flux-3-max/text-to-video y cuándo usarlo

flux-3-max/text-to-video es el endpoint de texto a vídeo de HiAPI: usted envía un prompt que describe una escena y el modelo devuelve un clip de vídeo generado. Es la herramienta adecuada cuando tiene una idea escrita en lugar de material ya existente —por ejemplo, un avance de producto, un clip corto para redes sociales, una vista previa de storyboard o planos de recurso generados en lote— y desea que la generación se ejecute como una tarea alojada en lugar de ejecutarla por su cuenta.

Encaja en flujos de trabajo donde el vídeo es solo una pieza de un proceso mayor. Un generador de guiones produce los prompts, flux-3-max/text-to-video los convierte en clips y su aplicación se encarga de almacenar o entregar el resultado. Como la llamada es asíncrona, también es adecuado para servicios backend que no pueden mantener una petición abierta durante todo el tiempo de renderizado.

No lo use cuando necesite una edición precisa fotograma a fotograma de un vídeo existente, ni cuando su prompt sea en realidad una sola imagen estática: para esto último, el endpoint de texto a imagen es más barato y más rápido. Si la salida debe reaccionar al material proporcionado, debería usar la variante de imagen a vídeo. Considere flux-3-max/text-to-video como el punto de entrada para generar clips a partir de prompts, y diseñe su integración en torno al envío de tareas en lugar de respuestas síncronas.

Estructura de la solicitud: endpoint, autenticación y payload

Cada solicitud a flux-3-max/text-to-video consta de tres partes: la ruta del endpoint, la cabecera de autenticación y un cuerpo JSON que indica el modelo y sus entradas.

Autenticación

HiAPI utiliza tokens bearer. Coloque su clave de API en la cabecera Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Mantenga la clave en el servidor. No la incruste en el código del cliente ni la confirme en el repositorio; cárguela desde una variable de entorno durante el desarrollo y desde un gestor de secretos en producción.

Identificador del modelo

En el cuerpo de la solicitud, el campo model selecciona el endpoint. Use el identificador exacto flux-3-max/text-to-video; un error tipográfico aquí es la causa más frecuente de solicitudes rechazadas.

Estructura del payload

El cuerpo mínimo contiene el nombre del modelo y el prompt:

{
  "model": "flux-3-max/text-to-video",
  "prompt": "Toma aérea lenta sobre un bosque de pinos cubierto de niebla al amanecer, iluminación cinematográfica"
}

Los campos opcionales —la duración y el interruptor de audio nativo— se explican en la sección siguiente. Como la generación es asíncrona, la respuesta inmediata a este POST es un objeto de tarea con un identificador que debe consultar repetidamente en lugar de recibir directamente el vídeo terminado. Diseñe el código para leer primero ese identificador y el resto de la información después.

Controlar la duración y el audio nativo

Dos controles a nivel de solicitud determinan el resultado que obtiene: la duración del clip y si el modelo genera audio junto con el vídeo.

Duración

Establezca la longitud del clip mediante el campo duration en el payload. Elija la duración más corta que satisfaga la narrativa: los clips cortos se renderizan más rápido, son más fáciles de revisar y siempre puede solicitar otro después. Antes de enviar, valide el valor según el rango documentado de flux-3-max/text-to-video; una duración fuera de rango se rechaza en el envío, y detectarlo localmente ahorra un viaje de ida y vuelta.

Audio nativo

El interruptor de audio nativo determina si el modelo genera una pista de audio junto con el clip. Actívelo cuando el vídeo se vaya a ver con sonido, y desactívelo cuando el vídeo vaya a estar silenciado, subtitulado o con una banda sonora independiente añadida en posproducción. Generar audio que va a descartar solo añade tiempo de tarea sin ningún beneficio.

Elija con criterio

Evite dejar que los valores predeterminados decidan por usted. Para una revisión rápida de storyboard, un clip corto y silencioso suele ser suficiente. Para material final de redes sociales, quizá el objetivo sea un clip más largo con audio nativo. Codifique esa elección en la configuración de la aplicación en lugar de fijarla en el punto de llamada, para poder cambiarla por función sin modificar el código de la solicitud. Envíe solo los campos que realmente quiera sobrescribir y deje que el endpoint aplique sus valores predeterminados al resto.

Solicitud curl funcional

La forma más rápida de confirmar credenciales y payload es enviar una tarea con una llamada curl.

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "Un barco de papel flotando por una calle empapada por la lluvia, farolas cálidas, profundidad de campo reducida",
    "duration": 5,
    "native_audio": false
  }'

Configure HIAPI_BASE_URL y HIAPI_API_KEY en su shell primero. Los valores de duración y audio aquí son solo ejemplos: use valores dentro del rango documentado para ese modelo.

Leer la respuesta inmediata

La respuesta es un objeto de tarea, no un vídeo. Contiene un job_id (o un identificador equivalente) y un estado como queued o processing. Guarde ese identificador; es el control que usará en cada llamada posterior. Si la respuesta parece un objeto de error, revise el código de estado y el mensaje antes de reintentar: un payload mal formado fallará del mismo modo cada vez.

Un envío correcto solo significa que la tarea fue aceptada, nada más. No intente buscar la URL del vídeo en la primera respuesta; no aparecerá allí hasta que la tarea se complete.

Gestionar el ciclo de vida de la tarea asíncrona

La generación de vídeo tarda de segundos a minutos, por lo que HiAPI la modela como una tarea. Su cliente envía una vez y luego comprueba el estado hasta que la tarea alcanza un estado terminal.

Estados

La tarea pasa de queued a processing y luego a un estado terminal: completed o failed. Solo los estados terminales son definitivos; cualquier estado intermedio significa seguir esperando.

Consultar sin saturar

Consulte el endpoint de estado con el identificador de tarea que guardó. Dos reglas mantienen sana la consulta:

• Espere entre consultas. Empiece con un intervalo corto y aumente progresivamente, o use un intervalo fijo claramente superior al tiempo típico en cola. Saturar el endpoint de estado no aporta nada.
• Establezca un límite. Limite el tiempo total de espera y el número total de intentos. Si para entonces la tarea no ha terminado, notifíquelo a su aplicación en lugar de entrar en un bucle infinito.

En un manejador web, no bloquee el hilo de la petición en un bucle de consulta. Envíe, guarde el identificador de la tarea, devuelva de inmediato y deje que un hilo de trabajo en segundo plano o el cliente consulten hasta completar el ciclo de vida. En escenarios por lotes, basta un bucle simple con sleep.

Leer el resultado

Cuando la tarea informa completed, la respuesta incluye una referencia de salida: una URL de vídeo o un identificador de recurso que su aplicación puede descargar o transmitir. En caso de fallo, lea el campo error; normalmente indicará el motivo (parámetro no válido, rechazo de contenido, error interno). Registre el identificador de la tarea junto con el mensaje de fallo para que las solicitudes de soporte o los reintentos estén fundamentados. Nunca trate un campo de salida ausente como un éxito; compruebe el estado explícitamente.

La misma solicitud en Python

El flujo con curl se traslada directamente a Python. Un cliente mínimo necesita envío, bucle de consulta y suficiente manejo de errores para distinguir una solicitud incorrecta de una tarea lenta.

import os, time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

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

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

Notas de implementación

raise_for_status() separa los errores de transporte y HTTP (autenticación, payload mal formado) de los fallos a nivel de tarea, que aparecen dentro de una respuesta correcta. La comprobación de failed lee explícitamente el campo error en lugar de suponer que el estado es completed. El límite de intentos convierte una espera ilimitada en una excepción predecible.

En producción, envuelva la consulta con una política de reintentos para errores de red transitorios y reutilice una única requests.Session. Si ejecuta muchas tareas, mueva wait a un hilo de trabajo en lugar de la ruta de la petición.

Diagnosticar fallos comunes

La mayoría de los problemas de integración se agrupan en unas pocas categorías. Cada una tiene un método de comprobación concreto.

Errores de autenticación

401 o 403 significa que la clave falta, ha caducado o tiene un formato incorrecto. Confirme que la cabecera Authorization existe, usa el esquema Bearer y que la variable de entorno está realmente cargada en el entorno de ejecución, no solo en su shell.

Payload mal formado

400 suele significar que el cuerpo no cumple el esquema. Verifique que el JSON se puede analizar, que model es exactamente flux-3-max/text-to-video y que la solicitud envía Content-Type: application/json. Use una biblioteca JSON para serializar en lugar de construir cadenas a mano.

Valores de parámetros no válidos

Una duración fuera del rango documentado, un nombre de campo desconocido o un tipo incorrecto en el interruptor de audio provocarán un rechazo en el envío. Valide localmente según los parámetros de la documentación del modelo antes de enviar.

Consultar demasiado pronto

Consultar de inmediato y repetidamente tras el envío no hace que la tarea termine antes. Use retroceso progresivo o un intervalo fijo, y deje que el objeto de tarea le indique cuándo ha salido del estado queued.

Fallos de tarea no gestionados

Una tarea que alcanza failed no implica necesariamente que su solicitud tenga un error: puede ser un rechazo de contenido o un error interno. Lea el mensaje de error, registre el identificador de la tarea y decida si reintentar con un prompt modificado o escalar el problema.

Tratar la respuesta de envío como resultado

Si su código espera la URL del vídeo inmediatamente después del envío, fallará. La primera respuesta es una tarea; solo el estado terminal incluye la salida. Una vez aplicadas estas seis comprobaciones, la mayoría de los problemas de integración quedan resueltos.