Cómo llamar a flux-3-video mediante la API de HiAPI: ejemplos de solicitud reales y funcionales con curl y Python

Qué ofrece flux-3-video a través de la API

Antes de escribir la primera línea de código, resultará útil saber qué puede hacer realmente el modelo flux-3-video a través de la API de HiAPI. Esta familia de endpoints abarca dos modos de invocación que comparten la misma estructura de solicitud, además de una capacidad de audio opcional que puedes activar o ignorar según tu caso de uso.

Dos modos de invocación

• Texto a vídeo: envías un prompt de texto y recibes un clip de vídeo recién generado. Usa este modo cuando solo tengas una idea y quieras que el modelo genere el movimiento, la composición y el ritmo.
• Continuación de vídeo: envías un clip de vídeo existente (o una referencia a él) junto con instrucciones, y el modelo lo prolonga. Úsalo cuando ya tengas material y quieras obtener más contenido sin costuras visibles.

Audio nativo

El modelo también puede producir audio nativo al mismo tiempo que genera el vídeo, controlado por parámetros opcionales en la misma carga útil de la solicitud. Dado que estos parámetros son opcionales, los flujos de trabajo puramente de vídeo pueden ignorarlos por completo: basta omitir los campos de audio y la solicitud se comporta exactamente igual que sin ellos.

El modelo mental central del que depende el resto de esta guía es el siguiente: no se trata de dos API independientes ni de dos tutoriales separados. Son dos formas de la misma solicitud; una vez comprendido el esqueleto compartido, cambiar entre ambas consiste solo en sustituir algunas entradas. Todo lo demás —credenciales, cabeceras, identificador del modelo, manejo de la respuesta— permanece igual.

Este diseño es intencional. Significa que tu código de autenticación, manejo de errores, lógica de reintentos y análisis de respuestas solo debe escribirse una vez y puede reutilizarse en ambos modos; añadir audio después tampoco te obligará a reescribirlo.

Autenticación, endpoint y anatomía de la solicitud

Cada llamada a flux-3-video sigue el mismo esqueleto. Domínalo una vez y los dos modos de invocación se convierten en variantes del mismo tema.

Credenciales

HiAPI autentica las solicitudes con una API key. La pasas mediante una cabecera, normalmente como bearer token. No escribas la clave en el código fuente: léela de una variable de entorno o de un gestor de secretos y asegúrate de que nunca entre en el sistema de control de versiones:

export HIAPI_API_KEY="your-key-here"

Endpoint e identificador del modelo

Las llamadas se envían a la URL base de la API de HiAPI, y la carga útil especifica el modelo explícitamente mediante el identificador flux-3-video. Escribir el nombre del modelo en el cuerpo de la solicitud en lugar de codificarlo en la URL significa que el mismo código cliente podrá apuntar a otro modelo en el futuro cambiando solo una línea.

Estructura de carga útil compartida

Independientemente del modo, la carga útil es un objeto JSON que, conceptualmente, contiene tres partes:

• El campo model: siempre flux-3-video.
• Las entradas que definen el modo: en texto a vídeo, un prompt; en la continuación, el clip de origen más un prompt. Esta es la única parte que cambia sustancialmente entre los dos modos.
• Modificadores opcionales: parámetros de audio y otros ajustes. Omitirlos produce el comportamiento predeterminado.

La pseudoestructura de una solicitud es la siguiente:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

La idea general es esta: un identificador de modelo, un objeto input anidado que contiene los campos específicos del modo, y claves opcionales que solo se añaden cuando son necesarias. Las siguientes secciones detallan cada modo.

Texto a vídeo: tu primera solicitud curl funcional

A continuación, una solicitud mínima pero completa que genera un vídeo a partir de un prompt. Supone que HIAPI_API_KEY ya está exportada en tu shell.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

Función de cada campo

• Authorization: transporta tu bearer token. Sin él, la solicitud se rechaza antes de que comience cualquier generación.
• Content-Type: application/json: el cuerpo es JSON, así que decláralo; omitirlo es una causa habitual de respuestas 4xx confusas.
• model: identifica flux-3-video como modelo de destino.
• input.prompt: la única entrada creativa obligatoria en el modo texto a vídeo. Redáctalo como describirías una toma: sujeto, movimiento, composición, iluminación, ambiente.

Consejos de redacción de prompts que valen la pena

Dado que el prompt es la única palanca creativa en este modo, su calidad determina directamente el resultado. Dos hábitos ayudan:

• Describe el movimiento, no solo el contenido. «A dolly shot through…» (una toma de travelling que atraviesa…) da al modelo un comportamiento de cámara que puede animar; una descripción estática no le ofrece nada que animar.
• Sé concreto. Las pistas concretas de iluminación y materiales («wet asphalt», «neon reflections») suelen producir imágenes más coherentes que los adjetivos abstractos.

Tras ejecutar esta solicitud y revisar la respuesta, habrás validado la clave, las cabeceras y la carga útil básica, que es la base de todo lo que sigue.

Continuación de vídeo: prolongar un clip existente

La continuación reutiliza el esqueleto de la sección anterior, pero la forma del objeto input cambia. El prompt ya no existe por sí solo, sino que se empareja con el clip de origen que el modelo debe prolongar.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

Qué cambia respecto a texto a vídeo

• Aparece una entrada de vídeo. Proporcionas el clip existente sobre el que el modelo debe construir. Esta es la diferencia decisiva entre ambos modos.
• El prompt pasa a ser orientativo, no generativo. En texto a vídeo describes toda la escena; aquí describes lo que ocurre a continuación. Redáctalo como una instrucción de continuación: hacia dónde va la cámara, qué entra en el encuadre, cómo evoluciona la escena.
• Todo lo demás es idéntico. El mismo endpoint, las mismas cabeceras, el mismo identificador de modelo, el mismo envoltorio input. Tu código cliente solo necesita ramificar al construir la carga útil.

Mantener la coherencia en la costura

El modelo necesita coincidir con el aspecto del clip de origen para evitar un corte visible. Las instrucciones breves y concretas que preservan el estilo existente suelen funcionar mejor que las descripciones largas que reimagina la escena. Si la primera continuación se desvía, acerca el prompt al contenido real del clip de origen en lugar de añadir más detalles en otros lugares.

Nota sobre las referencias de clips

La convención exacta de entrada para el clip de origen la define el esquema de entrada del modelo en HiAPI. Sigue ese esquema en lugar de adivinar el formato del campo: es la fuente autoritativa de qué acepta la entrada de continuación.

Añadir parámetros de audio nativo

El audio nativo es donde el patrón de modificadores opcionales demuestra su valor. Los parámetros de audio residen en el mismo objeto input que el resto de campos y, como son opcionales, las solicitudes de las dos secciones anteriores siguen siendo válidas sin ellos.

Dónde se ubican

La configuración de audio va dentro de input, junto a prompt y (en el modo continuación) video. Conceptualmente:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

Proteger los flujos de trabajo puramente de vídeo

La disciplina importante aquí es sencilla: trata el bloque de audio como puramente aditivo.

• No establezcas explícitamente los campos de audio en un valor «desactivado»: omítelos. Ausentar el bloque es más limpio que deshabilitarlo explícitamente y menos propenso a conflictos con futuros cambios de esquema.
• Construye la carga útil de forma incremental. Empieza con el cuerpo mínimo y añade la clave audio solo en la ruta de código en la que el usuario realmente solicite audio. Así tu ruta predeterminada coincidirá exactamente con los ejemplos puramente de vídeo.
• Antes de integrar el audio en producción, consulta el esquema para confirmar los nombres exactos de las flags y los valores aceptables. El nombrado de parámetros lo define el esquema de entrada del modelo en HiAPI; el nombre de bloque anterior solo muestra la ubicación, no garantiza la ortografía del campo.

Cuándo activarlo

Activa el audio cuando el entregable sea un clip de vídeo terminado y autocontenido: contenido para redes sociales, demostraciones, piezas narrativas breves. Mantenlo desactivado cuando vayas a añadir tu propia banda sonora o narración en una etapa posterior; generar audio que acabarás descartando desperdicia cómputo en el pipeline.

Como el audio viaja en la misma carga útil que todo lo demás, no hay una llamada separada, no hay una segunda credencial y no hay ramas adicionales de manejo de respuestas que mantener más allá de leer lo que devuelve la respuesta.

Escribir la misma solicitud en Python

Trasladar la llamada curl a Python es una tarea mecánica, porque la estructura de la solicitud es idéntica. El siguiente ejemplo usa solo la biblioteca estándar, por lo que funciona en cualquier entorno; si prefieres requests o httpx, su estructura también se corresponde directamente.

import json
import os
import urllib.request

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

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Modo continuación: adjuntar el clip de origen.
    if video is not None:
        input_block["video"] = video

    # El audio es estrictamente aditivo y se omite por defecto.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Texto a vídeo
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Continuación de vídeo con audio nativo
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

Por qué está organizado así

• Una función, dos modos. El parámetro video es opcional; cuando es None, la función genera una solicitud de texto a vídeo. Cuando se establece, la misma función genera una solicitud de continuación. No hay un cliente separado ni cabeceras duplicadas.
• El audio se activa explícitamente. La flag audio es False por defecto, por lo que el bloque de audio nunca se añade a menos que se solicite explícitamente; este es exactamente el patrón descrito anteriormente.
• La clave proviene del entorno. La API key se lee de HIAPI_API_KEY y nunca se codifica de forma rígida.

Al adaptarlo, solo tienes que sustituir la llamada a print por la acción que requiera tu pipeline: escribir la respuesta en un manifiesto, encolar tareas posteriores o notificar a una cola. La lógica de la solicitud en sí no necesita cambios.

Resolución de problemas y lista de verificación para producción

Cuando una llamada falle, recorre la siguiente lista en orden: cubre la gran mayoría de los problemas.

Lista de diagnóstico

• 401 o error de autenticación: ¿está HIAPI_API_KEY realmente exportada en el shell o proceso que ejecuta el código? Una clave configurada en un terminal no se transmite a un trabajo de cron.
• 415 o error de análisis inesperado: ¿está presente Content-Type: application/json? Omitirlo es el fallo silencioso más típico.
• La llamada de continuación devuelve 4xx: ¿incluye tu carga útil el clip de origen en la forma que espera el esquema de entrada del modelo? Una referencia de clip mal formada falla antes de que comience la generación.
• Falta audio en la salida: ¿entró realmente el bloque audio en la carga útil? Al depurar, registra el cuerpo serializado de la solicitud; es fácil construir el diccionario y olvidar adjuntar la clave.
• input vacío o truncado: imprime el JSON exacto que estás enviando. Casi todos los fallos «extraños» se resuelven al ver con tus propios ojos el cuerpo de la solicitud que viaja por el cable.

Antes de desplegar

• Nunca codifiques las claves de forma rígida. Usa siempre variables de entorno o un gestor de secretos.
• Registra tanto el cuerpo de la solicitud como el de la respuesta, al menos en el entorno de preproducción. Reproducir un fallo sin la carga útil exacta solo es adivinar.
• Trata los campos opcionales como opcionales. Construye la carga útil de forma incremental: primero el cuerpo mínimo, luego añade video y, por último, audio solo cuando sea necesario. Esto mantiene tu ruta predeterminada alineada con los ejemplos de la documentación.
• Mantén la selección de modo explícitamente visible en tu propio código. Una función con un parámetro video opcional está bien; un valor booleano enterrado tres niveles más adentro, no.
• Cada vez que añadas un campo, vuelve a consultar el esquema de entrada del modelo en HiAPI. Es la referencia autoritativa para los nombres de parámetros y los formatos aceptables, y estará más actualizada que cualquier tutorial.

Vale la pena reiterar el punto central: texto a vídeo, continuación y audio nativo son tres variantes de la misma forma de solicitud. Domina el esqueleto una vez y cada nueva capacidad será un cambio aditivo, no una reescritura. Feliz construcción.