Blog

Tutorial

Cómo usar flux-3 a través de la API de HiAPI: curl, Python y ejemplos de solicitudes ejecutables

Nov 10, 2026
Imagen de portada: placas de vidrio translúcido superpuestas y entrelazadas que refractan un fondo claro en franjas azules serenas, una composición geométrica abstracta con espacios en blanco equilibrados.
En esta página

Qué obtienes al usar flux-3 a través de HiAPI

flux-3 es un modelo de generación de imágenes que maneja tanto texto a imagen como imagen a imagen. Si estás construyendo una funcionalidad de producto, una herramienta de diseño o una canalización interna, la parte realmente interesante a menudo no es el modelo en sí, sino la limpieza con la que puedes colocarlo detrás de una interfaz estable y predecible, y mantenerlo así cuando cambian los requisitos.

Aquí es donde radica el valor de una plataforma de API agregadora. Llamar a flux-3 a través de HiAPI significa que tú:

  • Integras una sola vez. Una única URL base, un único método de autenticación y una estructura de solicitud y respuesta coherente entre los modelos que uses. Después, cambiar o comparar modelos es solo cuestión de modificar la configuración, no de reescribir código.
  • Te ahorras el trabajo de infraestructura. Sin alojar modelos, sin planificar capacidad de GPU, sin gestionar arranques en frío de tu lado. Envías una solicitud HTTP y manejas la respuesta.
  • Gestionas las credenciales de forma centralizada. Una sola clave de API que emitir, rotar y limitar en permisos, en lugar de establecer relaciones con cada proveedor upstream por separado.
  • Obtienes semántica de errores unificada. Los códigos de estado y las envolturas de error son los mismos sin importar qué modelo haya detrás de la llamada, lo que permite reutilizar la lógica de reintento y alertas.

En concreto para flux-3, esto significa que puedes pasar de un prototipo en un notebook a un endpoint de producción sin cambiar la estructura del código de tu cliente. Los dos modos de generación —texto a imagen e imagen a imagen— comparten la misma estructura de solicitud, así que admitir ambos depende de qué campos rellenes, no de qué SDK importes.

A lo largo de este artículo se usan las siguientes convenciones:

  • URL base: el endpoint de la API de HiAPI que aparece en la consola de tu cuenta.
  • Autenticación: bearer token en la cabecera Authorization.
  • Tipo de contenido: el cuerpo de la solicitud usa application/json; las entradas de imagen se proporcionan como URL o datos codificados en base64, según los límites de tamaño de tu carga útil.

Guarda la clave en una variable de entorno; nunca la confirmes en el control de código fuente. Los ejemplos siguientes leen la clave de HIAPI_API_KEY y el identificador del modelo de FLUX_MODEL, de modo que puedes ajustarlos sin modificar el código.

Con esto como base, la siguiente sección desglosa el cuerpo de la solicitud en sí.

Anatomía de la solicitud: texto a imagen e imagen a imagen

Una llamada a flux-3 se divide lógicamente en tres partes: la ruta del endpoint, las cabeceras de autenticación y un cuerpo JSON. El cuerpo es donde difieren los dos modos, y comprender esa diferencia te permite reutilizar un solo cliente para ambos.

Esqueleto compartido

Toda solicitud incluye campos de algún tipo:

  • model — el modelo a llamar; en este caso, tu identificador de flux-3.
  • input — el objeto que contiene las instrucciones de generación.
  • input.prompt — describe en lenguaje natural lo que quieres. Obligatorio en ambos modos.
  • Ajustes de generación opcionales — como tamaño de salida, relación de aspecto o pasos, según las capacidades que exponga el modelo. Configura solo los que necesites; los valores predeterminados suelen ser razonables.
  • Control asíncrono opcional — indicadores o callbacks que cambian cómo se ejecuta y entrega la tarea (detallado en la siguiente sección).

Texto a imagen

En el modo texto a imagen, prompt es el único campo sustancial. Describes la imagen, opcionalmente restringes la geometría de salida y envías. No hay imagen de origen, así que el modelo tiene la máxima libertad, lo que también significa que la calidad del prompt domina la calidad de la salida.

Un hábito útil: escribe el prompt como si le explicaras el encargo a un ilustrador humano. Ordena por sujeto, composición, iluminación, estilo y cualquier restricción dura (como «no incluir texto en la imagen» o «sujeto centrado»). Un prompt vago produce resultados mediocres sin importar cuántos pasos uses.

Imagen a imagen

En el modo imagen a imagen, añades un campo de imagen de origen además del prompt, y el prompt describe la transformación relativa a esa entrada, en lugar de una escena construida desde cero. Según la interfaz del modelo, esto puede implicar proporcionar una URL de imagen o una carga útil codificada, además de cualquier parámetro de intensidad o guía que controle cuánto se desvía la salida de la imagen de origen.

Para tu cliente de API, el impacto práctico es mínimo: el mismo endpoint, la misma autenticación, el mismo objeto input; solo un campo más. Ese es precisamente el objetivo de diseño. Tu función generate() debe aceptar una imagen de origen opcional y manejar la ramificación internamente, de modo que quien llama nunca necesite saber qué modo activó.

Estructura de la respuesta

La respuesta debe incluir un identificador de tarea y, al completarse, la ubicación de la imagen generada. Trata esa ubicación como un valor opaco: puedes obtenerla o almacenarla, pero no hagas suposiciones de análisis sobre su contenido. Algunas respuestas son inmediatas y otras son un identificador de tarea; por eso el manejo asíncrono debe incorporarse al diseño desde el primer día.

Parámetros y modo asíncrono

Elegir los ajustes de generación

Los ajustes de generación son un equilibrio entre calidad, latencia y costo. Estos principios aplican a la mayoría de los modelos de imagen, incluido flux-3:

  • Resolución y relación de aspecto afectan tanto la utilidad de la salida como el consumo de cómputo. Genera al tamaño que realmente entregarás; reducir una imagen grande desperdicia presupuesto, y ampliar una pequeña desperdicia renderizado.
  • Pasos o control de calidad mejoran la fidelidad hasta cierto punto y luego se estabilizan. Usa un prompt fijo para encontrar empíricamente ese punto de inflexión y detente ahí.
  • Control de determinismo (si está disponible) es importante para la reproducibilidad. Si necesitas volver a renderizar el mismo resultado para QA o soporte al usuario, registra los ajustes junto con la salida.

No adivines nombres de parámetros ni rangos aceptables; léelos en la documentación del modelo en la consola y toma esa como referencia. Si se rechaza un campo, la respuesta de error te dirá exactamente cuál.

Síncrono vs. asíncrono

La generación de imágenes no es una operación instantánea. Hay dos modos de ejecución:

Síncrono (bloqueante). Envías la solicitud y mantienes la conexión hasta que la imagen esté lista. Es simple y adecuado para tareas cortas, scripts y herramientas interactivas donde el usuario mira un indicador de carga. Pero también es frágil: las funciones serverless, los balanceadores de carga y los clientes móviles tienen límites de tiempo de espera, y un renderizado largo inevitablemente chocará con alguno de ellos.

Asíncrono (basado en tareas). Envías la solicitud, recibes un identificador de inmediato y luego consultas el endpoint de estado o recibes un callback hasta que la tarea informe que se completó. Elige este modo cuando:

  • Haya tiempos de ejecución serverless o de borde con límites estrictos de duración.
  • Necesites enviar en paralelo una gran cantidad de renderizados por lotes.
  • Cualquier flujo de interacción con el usuario en el que quieras devolver el control de inmediato y transmitir el progreso.

Diseña el cliente en torno a lo asíncrono y luego envuelve los casos simples con un método de conveniencia síncrono. Hacerlo al revés —forzar lo asíncrono dentro de un cliente bloqueante— rara vez da buenos resultados.

Al consultar el estado, usa retroceso exponencial con límite en lugar de un bucle ajustado fijo, establece un límite máximo de espera total y trata las tareas que nunca alcanzan un estado terminal como errores que merecen una alerta.

Una solicitud curl ejecutable

Empieza desde el terminal; una vez que el intercambio HTTP bruto esté claro, la versión en código es sencilla.

1. Configurar el entorno

export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"

Guarda el identificador del modelo en una variable; cambiar de modelo más adelante es solo cambiar una línea.

2. Enviar una solicitud de texto a imagen

curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLUX_MODEL"'",
    "input": {
      "prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
    }
  }'

El indicador -sS mantiene la salida limpia y aun así muestra los errores. Antes de ejecutar, confirma la ruta exacta con el endpoint registrado en la consola; la ruta tiene versión, así que toma la documentación como referencia.

3. Leer lo que devuelve

Pasa la respuesta por una herramienta de formato para que sea legible:

... | python -m json.tool

Fíjate en dos cosas: el identificador de la tarea y la ubicación de la imagen o el campo de estado que te dice que la tarea sigue en ejecución. Si ves un estado en lugar de una imagen, estás en la ruta asíncrona; anota el identificador y pasa a la consulta de estado.

4. Probar imagen a imagen

Añade la imagen de origen al objeto input y deja el resto igual:

curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLUX_MODEL"'",
    "input": {
      "prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
      "image": "https://example.com/source.jpg"
    }
  }'

Como la solicitud solo difiere en un campo, tu primera llamada exitosa ya valida la mayor parte de la integración. El resto —reintentos, almacenamiento, UI— es trabajo normal de aplicación.

La misma solicitud en Python

La llamada curl se traduce directamente. A continuación se muestra un cliente pequeño y reutilizable, en lugar de un script desechable.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def generate(prompt, image=None, timeout=60):
    """Submit a flux-3 generation job. Pass image= for image-to-image."""
    payload = {"model": MODEL, "input": {"prompt": prompt}}
    if image:
        payload["input"]["image"] = image

    resp = requests.post(
        f"{BASE}/v1/images/generations",
        headers=HEADERS,
        json=payload,
        timeout=timeout,
    )
    resp.raise_for_status()
    return resp.json()

Algunas decisiones deliberadas:

  • Una función, dos modos. El parámetro image cambia el comportamiento, y quien llama no necesita ramificar.
  • Tiempo de espera explícito. El comportamiento predeterminado de requests —esperar indefinidamente— es justo la forma de agotar un grupo de hilos de trabajo.
  • raise_for_status(). Hace que los fallos de la capa HTTP aparezcan como excepciones que puedes capturar en un solo lugar.

Añadir un auxiliar de consulta de estado

Cuando la respuesta trae un identificador de tarea en lugar de una imagen terminada, espera a que termine:

def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
    deadline = time.monotonic() + timeout
    delay = initial
    while time.monotonic() < deadline:
        r = requests.get(
            f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
        )
        r.raise_for_status()
        data = r.json()
        if data.get("status") in ("succeeded", "failed"):
            return data
        time.sleep(delay)
        delay = min(delay * factor, cap)
    raise TimeoutError(f"job {job_id} did not finish in {timeout}s")

Ajusta el nombre del campo de estado según la estructura de respuesta documentada. La estructura en sí —retroceso con límite, fecha límite estricta, comprobación de estado terminal— es lo clave, y se aplica tal cual cuando cambias de modelo.

Combinarlo todo

if __name__ == "__main__":
    result = generate(
        "A minimal studio photograph of a ceramic mug, soft side light"
    )
    if "id" in result and not result.get("output"):
        result = wait_for(result["id"])
    print(result)

A continuación, envuelve generate con tu propia capa de reintentos y registro, y la integración ya tendrá forma de producción.

Control de costos y errores comunes

Mantener el gasto predecible

La generación de imágenes se factura por solicitud, y el monto depende del modelo y los ajustes; consulta el panel de precios en tiempo real de la consola en lugar de asumir valores codificados. La disciplina de ingeniería es lo que protege el presupuesto:

  • Establece límites por usuario y por tarea en tu propio código. La plataforma aplica límites a nivel de cuenta; tu aplicación debe aplicar límites a nivel de producto para que un solo cliente descontrolado no agote la cuenta.
  • Cachea de forma agresiva. Calcula un hash del prompt normalizado más los ajustes y reutiliza las salidas almacenadas. Las solicitudes idénticas son comunes en editores y escenarios de vista previa.
  • Genera a la resolución de entrega. Renderiza el tamaño que vas a mostrar; evita el patrón costoso de «renderizar grande y luego reducir».
  • Coloca la regeneración detrás de una acción explícita del usuario. Regenerar automáticamente con cada tecla que se escribe en el campo de prompt es el multiplicador de costos accidentales más común.
  • Registra el modelo, los ajustes y la latencia de cada llamada. Sin eso, no puedes saber qué funcionalidad cuesta mucho.
  • Valida la entrada antes de enviar. Rechaza en el cliente prompts vacíos o anormalmente largos, para que nunca pagues por solicitudes que van a fallar con seguridad.

Depurar los fallos que realmente encontrarás

Recorre esta lista en orden; resuelve la mayoría de los incidentes.

  1. 401 / 403 — autenticación. ¿La clave se cargó en el entorno donde realmente se ejecuta la solicitud? Una clave disponible en tu shell puede no existir en el contenedor. Confirma que el prefijo Bearer y el nombre de la cabecera sean exactamente correctos.
  2. 404 — ruta o modelo incorrecto. Tanto las rutas versionadas como los identificadores de modelo cambian. Compara carácter por carácter con el endpoint documentado.
  3. 422 / 400 — carga útil rechazada. El cuerpo del error indicará el campo problemático. Sospechosos habituales: tipo incorrecto, falta de prompt o parámetro no admitido. Vuelve a enviar quitando los ajustes opcionales para aislar el problema.
  4. 429 — límite de velocidad alcanzado. Retrocede con jitter y reintenta; no reintentes inmediatamente en bucle. Distínguelo del agotamiento de cuota a nivel de cuenta, donde reintentar no ayuda.
  5. Tiempos de espera. Si la solicitud tarda demasiado, estás bloqueando donde deberías consultar el estado. Cambia al flujo asíncrono y establece tiempos de espera del cliente de forma consciente.
  6. Tarea atascada en pending. Consulta el estado con una fecha límite y trata el tiempo de espera como un fallo que merece alerta, no como una espera infinita.

Un hábito que une toda la lista: registra el cuerpo de error completo, no solo el código de estado. El cuerpo de error normalmente te dice exactamente qué campo o límite falló, lo que convierte media hora de depuración en una corrección de una línea.

Primero haz que la llamada curl funcione, luego pórtala al cliente anterior, centraliza la consulta de estado y el manejo de errores en un solo lugar, y el resto de la integración será código de aplicación normal. Para conocer las capacidades actuales del modelo y los precios, consulta la documentación de flux-3 y el panel de precios en la consola de HiAPI.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API