Tutorial
Cómo usar flux-3 a través de la API de HiAPI: curl, Python y ejemplos de solicitudes ejecutables
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
imagecambia 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.
- 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
Bearery el nombre de la cabecera sean exactamente correctos. - 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.
- 422 / 400 — carga útil rechazada. El cuerpo del error indicará el campo problemático. Sospechosos habituales: tipo incorrecto, falta de
prompto parámetro no admitido. Vuelve a enviar quitando los ajustes opcionales para aislar el problema. - 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.
- 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.
- 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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio