Tutorial
Cómo llamar a flux-2/text-to-image mediante la API de HiAPI: tutorial con curl y Python
Ejercicio de solicitud funcional: identificador de modelo, prompt y parámetro de relación de aspecto, campos de respuesta y manejo de errores
En esta página
Qué expone flux-2/text-to-image a través de la API
Antes de escribir la primera línea de código, conviene tener claro a qué te estás conectando. En HiAPI, flux-2/text-to-image no es un SDK independiente que debas instalar ni un servicio nuevo con autenticación propia. Es un identificador de modelo que se pasa, junto con el prompt que describe la imagen que deseas, al endpoint compartido de generación de imágenes.
Este modelo mental importa porque delimita el alcance de la integración. Tu código necesita tres cosas:
- Credenciales de autenticación para la API de HiAPI.
- El endpoint que acepta solicitudes de generación de imágenes.
- Una carga útil JSON que contenga
model(establecido enflux-2/text-to-image) yprompt.
Todo lo demás —la relación de aspecto, las preferencias de salida y cualquier otro ajuste que exponga el modelo— existe como campos adicionales dentro de esa carga útil. Por eso cambiar de otro modelo de texto a imagen a flux-2/text-to-image suele requerir solo modificar una línea de configuración, en lugar de reescribir el código: el sobre de la solicitud se mantiene y solo cambia el valor de model.
El endpoint recibe tu solicitud, la ejecuta a través del modelo y devuelve una respuesta estructurada que contiene la imagen generada (normalmente una URL o una carga codificada) junto con metadatos del trabajo. Para una llamada básica no necesitas consultar una cola de trabajos separada: desde la perspectiva del cliente, el ciclo de solicitud y respuesta es síncrono, pero la generación subyacente sigue llevando tiempo, así que el tiempo de espera de tu cliente HTTP debería ser generoso.
Quédate con esta idea: un endpoint, una carga útil, una cadena de modelo. El resto de este tutorial rellenará la carga útil y reforzará la llamada.
Construir una solicitud funcional con curl
La forma más rápida de confirmar que las credenciales y la estructura de la carga útil son correctas es una llamada con curl. Consigue una respuesta exitosa en la terminal antes de pasar a Python: esto aísla los problemas de autenticación y de carga útil de los errores propios del lenguaje.
Primero, define la clave como variable de entorno para que no quede en texto plano en el historial del shell:
export HIAPI_API_KEY="your_api_key_here"
Después envía la solicitud:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/text-to-image",
"prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
"aspect_ratio": "16:9"
}'
Puntos a revisar al ejecutar:
- El endpoint y la clave provienen del panel de tu cuenta de HiAPI. Copiar el endpoint desde el panel en lugar de volver a escribirlo evita el fallo silencioso más común: que la solicitud se envíe a un lugar inesperado.
-sSmantiene la salida limpia, pero sigue mostrando errores de nivel de curl, como fallos de DNS o TLS.- La cabecera
Authorizationusa el esquema bearer estándar. No debe haber espacios finales ni comillas alrededor de la expansión de la variable. Content-Type: application/jsones obligatorio; sin él, el cuerpo puede rechazarse antes de que el modelo lo vea.
Si la llamada tiene éxito, verás el cuerpo JSON de la respuesta en la terminal. Pásalo por un formateador para mejorar la legibilidad:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
| python3 -m json.tool
Cuando esto funcione, tendrás una línea base que sabes que funciona. Cualquier fallo posterior en Python podrá compararse con esta llamada que confirmaste como válida.
El prompt y el parámetro de relación de aspecto
Hay dos campos de la solicitud que más influyen en la salida: prompt y aspect_ratio. Ajusta solo uno a la vez; de lo contrario, no podrás saber cuál de los dos provocó el cambio que observas.
Prompt
El prompt es la descripción en lenguaje natural de la imagen. Escríbelo como una descripción compacta de la escena, no como una lista de palabras clave: aproximadamente en el orden de sujeto, escenario, iluminación y composición. Compara:
- Vago:
a lighthouse - Concreto:
a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot
Mantén la redacción explícita y estable durante la experimentación. Si reescribes el prompt y la relación de aspecto en la misma iteración, tendrás dos variables y una sola observación. Congela el prompt, ajusta una palabra a la vez y registra el cambio real.
Hábitos prácticos:
- Coloca el sujeto más importante al principio de la cadena.
- Describe la iluminación y la atmósfera con palabras concretas, no abstractas.
- Mantén un pequeño conjunto de prompts de referencia en tu base de código y vuelve a ejecutarlos cada vez que cambies cualquier otra cosa, para poder distinguir un cambio de comportamiento del modelo de un cambio en el prompt.
Relación de aspecto
aspect_ratio controla la forma de la salida: panorámica para paisajes y banners, cuadrada para avatares y miniaturas, vertical para pósteres y diseños móviles. El modelo acepta cadenas de proporción como 16:9, 1:1 o sus equivalentes verticales; usa las proporciones documentadas para el modelo, no inventes otras.
Como la relación de aspecto es un único campo discreto, es el parámetro más fácil de explorar. Escribe un bucle que mantenga el prompt fijo y solicite la misma imagen en tres proporciones, y luego compara las composiciones en paralelo. Pronto sabrás qué proporciones recortan el sujeto y cuáles le dan espacio.
Una advertencia: la relación de aspecto cambia la composición efectiva, no solo el lienzo. Un prompt escrito para una toma panorámica puede quedar escaso en un encuadre cuadrado. Una vez que decidas la proporción, revisa el prompt una vez para compensarlo.
Trasladar la llamada a Python
La llamada con curl se traduce directamente a Python. El objetivo es escribir una función pequeña que reciba el prompt y la relación de aspecto, lea la clave del entorno y devuelva el JSON analizado: una forma apta para producción, no un script desechable.
import os
import requests
IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # fail fast if unset
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
IMAGE_ENDPOINT,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
Notas sobre por qué está escrito así:
- Usa variables de entorno, no literales.
os.environ[...]lanza unKeyErrorinmediatamente si falta la variable, lo cual es mucho mejor que enviar un token bearer vacío y luego tener que descifrar un error de autenticación confuso. json=payloadhace querequestsserialice el cuerpo y establezcaContent-Typepor ti. No construyas cadenas JSON a mano.- Tiempo de espera explícito. La generación de imágenes no es instantánea; el tiempo de espera predeterminado del cliente te dará problemas bajo carga. Establécelo a propósito.
raise_for_status()convierte las respuestas que no son 2xx en excepciones que puedes capturar y clasificar, en lugar de devolver silenciosamente un cuerpo de error que parece datos.
Llámalo así:
result = generate_image(
"a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
aspect_ratio="16:9",
)
print(result)
Si prefieres httpx, la forma es idéntica: cambia la importación y conserva las mismas cabeceras, la carga útil con json= y el parámetro de tiempo de espera. Lo importante es la carga útil, que permanece igual que en la versión con curl.
Leer la respuesta
Una llamada exitosa devuelve un objeto JSON. En lugar de adivinar los nombres de los campos, inspecciona primero una respuesta real y luego escribe el analizador según lo que veas realmente. Ejecuta tu función e imprime las claves de nivel superior:
result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())
Los campos que normalmente usarás se dividen en dos grupos:
- La imagen en sí. La respuesta incluye la imagen generada, normalmente una URL que puedes descargar o servir, y a veces datos de imagen codificados. Lee el nombre exacto del campo en tu propia respuesta, guarda ese valor y procésalo según su forma. Si es una URL, trátala como de corta duración: descárgala o cópiala a tu propio almacenamiento a tiempo, en lugar de guardar el enlace en una base de datos y asumir que seguirá resolviéndose el mes que viene.
- Metadatos. Espera campos acompañantes que describan la generación: el modelo usado, la relación de aspecto o el tamaño solicitados y un identificador de la solicitud. Regístralos junto con la imagen. Cuando un usuario informe de que una imagen "no se ve bien", los metadatos te dirán qué prompt y qué proporción la produjeron sin que tengas que reconstruirlo desde el estado de la aplicación.
Un patrón de extracción seguro:
image_ref = result.get("image") or result.get("data")
if not image_ref:
raise ValueError(f"no image in response; keys={list(result.keys())}")
Esto es deliberadamente defensivo. Los nombres de los campos son estables dentro del modelo, pero escribir el acceso de forma que falle de manera ruidosa mostrando la lista real de claves evita que un None silencioso se propague a tu interfaz. Una vez confirmados los nombres de los campos a partir de una respuesta real, ajusta el código para leerlos directamente.
Por último, no descartes la respuesta sin procesar. Guárdala (o registra en un log parte de las solicitudes) hasta que tu integración se estabilice: es la fuente de verdad cuando algo falla más adelante.
Errores comunes y cómo solucionarlos
La mayoría de los fallos en la primera ejecución pertenecen a unas pocas categorías. Gestiónalos por clase de estado HTTP, no comparando el texto del mensaje, que cambia sin aviso.
Fallos de autenticación (401 / 403)
Falta la clave, tiene un formato incorrecto o carece de permiso de acceso. Comprueba en orden: si HIAPI_API_KEY está realmente definida en el entorno que ve tu proceso; si la cabecera es exactamente Authorization: Bearer <key>, sin espacios adicionales ni comillas envolventes; y si enviaste por accidente una clave de un entorno distinto. Si curl funciona y Python no, imprime la cabecera que envías y compárala carácter por carácter.
Carga útil mal formada (400)
El cuerpo se rechaza antes de la generación. Causas habituales: JSON inválido (cadenas construidas a mano con comas finales), falta de prompt o un Content-Type incorrecto. La solución es usar json=payload en Python y -d con JSON válido en curl. Muestra en el log la carga útil que estás a punto de enviar y léela como lo haría una persona.
Parámetros no admitidos o inválidos (400 / 422)
Nombres de campo o valores que el modelo no acepta: un aspect_ratio mal escrito, una proporción no documentada para el modelo o un campo adicional copiado del ejemplo de otro modelo. Reduce la carga útil al mínimo (model, prompt) y luego añade los campos uno a uno para localizar el problema.
Límite de velocidad (429)
Estás enviando solicitudes más rápido de lo que permite el límite de tu cuenta. Es temporal. No reintentes en un bucle apretado: usa retroceso exponencial con un límite de intentos. Si procesas por lotes, añade una pequeña pausa entre llamadas en lugar de enviarlas todas de golpe.
Errores del servidor (5xx) y tiempos de espera
Son temporales y están fuera de tu control. Reintenta con retroceso y asegúrate de que el tiempo de espera sea lo bastante largo para que una generación lenta no se clasifique erróneamente como fallo. Un tiempo de espera de lectura que se dispara mientras el modelo sigue trabajando genera un reintento que desperdicia una solicitud.
Mantener la clasificación en un solo lugar facilita el mantenimiento:
def classify(status: int) -> str:
if status in (401, 403):
return "auth" # fix config, do not retry
if status in (400, 422):
return "payload" # fix request, do not retry
if status == 429:
return "rate_limit" # retry with backoff
if status >= 500:
return "server" # retry with backoff
return "other"
Encapsular la llamada para producción
La función anterior funciona, pero una integración real necesita tres cosas que aún no tiene: reintentos que distingan fallos temporales de permanentes, tiempos de espera que reflejen la realidad y logs que te permitan reconstruir lo ocurrido. Un pequeño envoltorio cubre las tres.
import logging
import time
log = logging.getLogger(__name__)
def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, aspect_ratio)
except requests.HTTPError as exc:
status = exc.response.status_code
kind = classify(status)
log.warning("flux-2 call failed", extra={
"attempt": attempt, "status": status,
"kind": kind, "aspect_ratio": aspect_ratio,
})
if kind in ("auth", "payload"):
raise # retrying will not help
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
Por qué cada parte aporta valor:
- Reintenta solo lo que se puede reintentar. Los errores de autenticación y de carga útil son deterministas: reintentarlos pierde tiempo y oculta el bug real. Los límites de velocidad, los errores del servidor y los tiempos de espera obtienen retroceso exponencial.
- Registra campos estructurados, no prosa. El número de intento, el estado, la clase de error y los parámetros usados te permiten agrupar fallos después. Nunca registres la clave de la API.
- Limita el número de intentos. Un bucle de reintentos sin límite convierte un fallo en un proceso de trabajo colgado.
- Mantén el tiempo de espera explícito y holgado. Pásalo desde la configuración para poder aumentarlo en las franjas lentas conocidas sin tocar el código.
Otros dos hábitos que rinden: guardar un hash de (model, prompt, aspect_ratio) por cada imagen generada, para poder reproducir cualquier salida; y mantener un pequeño conjunto de prompts de referencia en el conjunto de pruebas, ejecutándolos después de cualquier cambio en el envoltorio. Juntos convierten un fragmento de tutorial en algo operable.
Con la forma de la solicitud fijada y el manejo de errores en su sitio, cambiar de modelo más adelante solo requiere una línea en el campo model: exactamente el sentido de llamar a flux-2/text-to-image a través de una interfaz unificada.
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