Tutorial
Cómo llamar a flux-3-image-klein mediante la API de HiAPI: curl, Python y ejemplos de solicitud funcionales
Práctica de integración para desarrolladores: de la primera solicitud a llamadas por lotes fiables
- Modelo
- flux-3-image-klein
En esta página
Requisitos reales de la integración de flux-3-image-klein
Antes de escribir la primera línea de código, aclara cuántos pasos separan tu script de una imagen generada. Para flux-3-image-klein en HiAPI, la lista es corta: un endpoint, una credencial, un cuerpo de solicitud JSON y un objeto de respuesta que hay que analizar.
Este es el modelo mental que conviene tener presente:
- Endpoint — una ruta de HiAPI gestiona la generación de imágenes de este modelo. Todas las solicitudes apuntan ahí; el modelo se identifica en el cuerpo de la solicitud, no mediante URL distintas.
- Credencial — una clave de API emitida desde tu cuenta de HiAPI. Se transmite en cada llamada mediante una cabecera HTTP. Trátala como una contraseña: léela desde una variable de entorno y nunca la codifiques directamente en un archivo que pueda acabar en un commit.
- Cuerpo de la solicitud — un objeto JSON pequeño que describe el modelo, el prompt y unos pocos parámetros opcionales que influyen en la salida (tamaño, indicaciones relacionadas con el estilo, etc.).
- Respuesta — un objeto JSON que, al analizarlo, proporciona la referencia a la imagen generada y los metadatos que la API devuelve junto con ella.
Antes de empezar hay dos requisitos previos que merece la pena comprobar. Primero, confirma que tu clave está activa y tiene permiso de generación de imágenes: una clave válida para una modalidad no lo es automáticamente para otra. Segundo, abre la documentación actual de HiAPI en una pestaña. Los nombres de parámetros, los tamaños admitidos y los campos de respuesta pueden cambiar, y la documentación es la única fuente de verdad con la que debes contrastar, no la memoria ni algún artículo de blog (incluido este).
El resto de esta guía construye una solicitud, la migra a Python y luego la refuerza para cargas reales. Si la sigues en orden, cada paso reutiliza el anterior y no hay nada que reaprender a mitad de camino.
Enviar la primera solicitud funcional con curl
La forma más rápida de confirmar que la integración funciona es hacer una llamada con curl desde la shell. Una vez que obtengas una respuesta correcta aquí, todo lo demás será solo empaquetado.
Primero exporta tu clave para que nunca aparezca como literal en el historial de la shell:
export HIAPI_API_KEY="your-api-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
Luego envía una solicitud mínima:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-3-image-klein",
"prompt": "Un faro desgastado por la intemperie en un acantilado al atardecer, exposición larga, niebla suave"
}'
Nota sobre la URL: la ruta base y la ruta exactas las define la documentación de HiAPI; usa el endpoint de la documentación y no copies el nombre de host de ninguna captura de pantalla de terceros. Define HIAPI_BASE_URL una vez en el entorno y todos los ejemplos posteriores la reutilizarán.
Ahora veamos qué hace cada campo:
modelidentifica qué modelo procesa la tarea. Debe coincidir exactamente con la documentación; un error tipográfico aquí es la causa más habitual de que una solicitud parezca válida pero no devuelva resultados útiles.promptes tu descripción en lenguaje natural. Sé concreto sobre el sujeto, la composición, la iluminación y la atmósfera: el modelo responde a los detalles descriptivos, y los prompts vagos producen resultados impredecibles que no se pueden depurar.- Las cabeceras no son negociables: el token bearer autentica y
Content-Type: application/jsonindica al servidor cómo analizar el cuerpo de la solicitud.
Si tiene éxito, obtendrás una respuesta JSON que contiene la referencia a la imagen generada (normalmente una URL o un recurso alojado) y metadatos. Si quieres inspeccionar también las cabeceras de respuesta, imprime primero la respuesta completa con curl sin la supresión de -sS, aclara la estructura y luego reduce la salida. Guarda una respuesta real en un archivo: la usarás como fixture de prueba al escribir y probar el cliente de Python.
Si falla, no caigas en la tentación de modificar el cuerpo de la solicitud al azar. Revisa primero el código de estado y el cuerpo del mensaje de error; la sección de solución de problemas más adelante en esta guía asigna cada tipo de fallo a una corrección concreta.
Migrar la solicitud a Python
Cuando curl funcione, migra a Python sin cambiar la semántica. El objetivo no es construir un framework, sino un cliente pequeño que se comporte exactamente igual que el comando de shell y sea fácil de ampliar.
El enfoque más limpio es colocar el cuerpo de la solicitud en un único lugar compartido, de modo que las versiones de curl y Python nunca diverjan. Defínelo como un diccionario, serialízalo y deja que un envoltorio ligero se encargue de lo relacionado con HTTP.
import json
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def build_payload(prompt: str, **overrides) -> dict:
payload = {
"model": "flux-3-image-klein",
"prompt": prompt,
}
payload.update(overrides)
return payload
def generate_image(prompt: str, timeout: float = 60.0, **overrides) -> dict:
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(build_payload(prompt, **overrides)),
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"Un faro desgastado por la intemperie en un acantilado al atardecer, exposición larga, niebla suave"
)
print(json.dumps(result, indent=2))
Por qué esta estructura vale la pena:
build_payloades el único lugar donde se ensambla el cuerpo de la solicitud. Si añades un parámetro allí, tanto los scripts de exploración como el código de producción lo obtienen automáticamente.raise_for_status()convierte inmediatamente los fallos HTTP en excepciones, de modo que nunca tomarás por accidente un cuerpo de respuesta de error como un resultado correcto.- Un
timeoutexplícito evita el clásico problema de bloqueo: una conexión estancada que bloquea indefinidamente un hilo de trabajo. Elige un valor que coincida con el presupuesto de tiempo propio del servicio. - Que la URL base y la clave provengan de variables de entorno significa que el mismo código se ejecuta sin cambios en preproducción y producción.
Ejecútalo y compara la salida con la respuesta de curl que guardaste antes. Deberían describir la misma estructura. Si difieren, la migración introdujo un bug: corrígelo ahora, antes de que añadas lotes y reintentos, cuando las diferencias serán mucho más desagradables.
Gestionar los parámetros de tamaño y estilo
El prompt resuelve la mayor parte, pero los parámetros que influyen en la imagen —el tamaño de salida y las indicaciones relacionadas con el estilo— son donde la integración falla de forma silenciosa. Dos reglas te mantienen a salvo.
Coloca los parámetros opcionales en un bloque explícito
Nunca disperses cadenas mágicas por todo el código. Amplía el constructor del cuerpo de la solicitud con parámetros con nombre y valida en el límite:
def build_payload(prompt: str, size: str | None = None, style: str | None = None) -> dict:
payload = {"model": "flux-3-image-klein", "prompt": prompt}
if size:
payload["size"] = size
if style:
payload["style"] = style
return payload
Omitir por completo un parámetro suele ser mejor que enviar una cadena vacía o un marcador de posición. Si no necesitas controlar el tamaño, omítelo y deja que el servicio aplique su valor predeterminado documentado.
Valida según la documentación, no según suposiciones
Esta es la parte que la mayoría de los tutoriales omite: no codifiques directamente listas de tamaños o valores de estilo "admitidos" tomadas de artículos de blog. Los valores admitidos pueden cambiar, y las constantes obsoletas se convierten en errores 400 en tiempo de ejecución difíciles de rastrear. En su lugar:
- Lee la referencia actual de parámetros de flux-3-image-klein en la documentación de HiAPI, registra los valores aceptables como una constante en tu base de código y añade un comentario con la página de la documentación y la fecha de la comprobación.
- Antes de construir la solicitud, valida la entrada del usuario o del llamador con esa constante. Falla rápido con un mensaje de error local claro en lugar de enviar por la red una solicitud condenada al fracaso.
- Cuando una solicitud devuelva un error de validación por un valor no admitido, actualiza la constante a partir de la documentación en lugar de adivinar un valor cercano que "parezca correcto".
Una pequeña tupla ALLOWED_SIZES más una comprobación de pertenencia cuestan casi nada y eliminan toda una clase de incidencias de soporte. Lo mismo vale para las indicaciones de estilo: trátalas como un conjunto cerrado que has validado, no como una cadena abierta que esperas que el servidor tolere.
Solicitudes por lotes y reintentos de fallos
Una sola solicitud en un script es solo una demostración. Una carga real implica decenas o miles de imágenes, y ahí es donde importa la disciplina en la capa de cliente. Coloca la lógica de procesamiento por lotes y reintentos en el módulo de cliente, no en un bucle improvisado pegado en un notebook: querrás tener un único lugar donde observarla y ajustarla.
Concurrencia con trazabilidad
Un patrón sencillo es un grupo de hilos acotado en el que cada tarea enviada devuelve tanto la entrada como el resultado:
from concurrent.futures import ThreadPoolExecutor, as_completed
def run_batch(prompts: list[str], max_workers: int = 4) -> list[dict]:
results = []
with ThreadPoolExecutor(max_workers=max_workers) as pool:
futures = {pool.submit(generate_image, p): p for p in prompts}
for future in as_completed(futures):
prompt = futures[future]
try:
results.append({"prompt": prompt, "ok": True, "data": future.result()})
except Exception as exc:
results.append({"prompt": prompt, "ok": False, "error": str(exc)})
return results
Aquí hay dos características importantes. Primera, cada resultado se asocia a su prompt, de modo que los fallos parciales son atribuibles y no un misterio. Segunda, max_workers es la perilla que puedes controlar: empieza con un valor conservador, observa la tasa de errores y aumenta la concurrencia solo después de que una ejecución por lotes salga limpia. Saturar el endpoint con paralelismo ilimitado es la forma más rápida de convertir una integración sana en un incidente de limitación de tasa.
Reintentos con retroceso
Reintenta solo lo que es seguro: errores de red transitorios, tiempos de espera agotados y respuestas de limitación de tasa. No reintentes errores de validación: la solicitud fallará igual todas las veces y solo desperdiciarás cuota.
import time
def generate_with_retry(prompt: str, attempts: int = 3, **overrides) -> dict:
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, **overrides)
except requests.HTTPError as exc:
status = exc.response.status_code if exc.response is not None else None
if status is not None and 400 <= status < 500 and status != 429:
raise
if attempt == attempts:
raise
except requests.Timeout:
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
raise RuntimeError("unreachable")
Registra una línea de log por intento con el identificador del prompt, el número de intento y el estado. Cuando una ejecución por lotes falle, esa línea es la que te dice si te enfrentas a un fallo transitorio o a un problema sistemático en el cuerpo de la solicitud.
Solucionar errores comunes de solicitud
La mayoría de los fallos de la primera semana no son problemas del modelo, sino de la tubería. Estas son las categorías que más probablemente encuentres y su corrección concreta.
401 / 403 — autenticación y autorización
Síntoma: rechazo inmediato antes de que ocurra cualquier generación.
Causa: falta la cabecera Authorization, el token bearer tiene un formato incorrecto, la clave ha caducado o ha sido revocada, o se pegaron caracteres en blanco en la variable de entorno.
Corrección: imprime los primeros y últimos caracteres de la clave que realmente envías (nunca la clave completa), confirma que el formato de la cabecera es Bearer <key> con exactamente un espacio, y verifica que la clave está activa en la cuenta de HiAPI. Si la clave funciona en curl pero no en Python, la diferencia casi siempre está en cómo se ensambla la cabecera.
400 — validación del cuerpo de la solicitud
Síntoma: la solicitud se entiende, pero se rechaza por algún campo.
Causa: model mal escrito, falta prompt, un valor de size o estilo no admitido, o un tipo incorrecto (se envió un número donde se esperaba una cadena).
Corrección: compara tu cuerpo de solicitud serializado —json.dumps(build_payload(...))— carácter por carácter con el esquema de la documentación. Valida localmente los parámetros opcionales con las constantes derivadas de la documentación para que los valores incorrectos nunca salgan de tu proceso.
404 — ruta incorrecta
Síntoma: el endpoint en sí no se encuentra. Causa: ruta mal escrita, URL base obsoleta o barras finales desajustadas al concatenar fragmentos de URL. Corrección: construye la URL a partir de una única constante y contrástala con la referencia de endpoints de la documentación de HiAPI, no con fragmentos de código copiados.
429 — limitación de tasa
Síntoma: las solicitudes empiezan a funcionar y luego fallan en bloque bajo carga.
Corrección: reduce max_workers, respeta la estrategia de retroceso que ya tienes en el envoltorio de reintentos y trata el 429 como un error transitorio. Si los 429 persisten con baja concurrencia, lo que hay que revisar son los límites o el patrón de uso de tu cuenta, no el código.
Tiempos de espera agotados y restablecimientos de conexión
Síntoma: la llamada se queda colgada mucho tiempo o aparecen excepciones ReadTimeout a mitad de un lote.
Causa: un tiempo de espera del cliente demasiado agresivo, una red inestable o un lote grande que agota el grupo de conexiones.
Corrección: define un tiempo de espera explícito pero realista para cada solicitud, reintenta los tiempos de espera agotados con retroceso y mantén la concurrencia moderada. Nunca elimines el tiempo de espera "para que funcione": eso convierte un fallo visible en un bloqueo invisible.
Éxito pero la imagen no es la correcta
Esto es un problema del prompt, no de la API. Los prompts vagos, las indicaciones de estilo contradictorias y los prompts que chocan con un size explícito producen salidas inesperadas. Refina primero la descripción del prompt; solo después revisa los parámetros.
Lista de verificación antes del lanzamiento
Antes de dirigir tráfico de producción a flux-3-image-klein, repasa esta lista. Solo lleva unos minutos y captura los fallos que resultan caros en producción.
- Credenciales — la clave se carga desde variables de entorno o un gestor de secretos y nunca se confirma en el repositorio; confirma que funciona para la generación de imágenes en la cuenta con la que pretendes facturar.
- Endpoint — la URL base y la ruta se toman literalmente de la documentación actual de HiAPI y se guardan como una única constante.
- Estructura del cuerpo de la solicitud — el nombre del modelo está escrito exactamente como en la documentación, el prompt siempre existe y no está vacío, y los parámetros opcionales se omiten cuando no se usan y se validan localmente cuando se establecen.
- Valores de los parámetros — tus constantes de
sizey estilo se han comprobado contra la documentación en la fecha indicada en el comentario, y hay un plan para volver a comprobarlas cuando la API se actualice. - Estrategia de reintentos — los errores transitorios y los tiempos de espera agotados se reintentan con retroceso, los errores de cliente fallan rápido y el número de intentos tiene un límite.
- Concurrencia —
max_workersse establece de forma conservadora y solo se aumenta después de ejecuciones por lotes limpias. - Tiempos de espera — se establecen explícitamente en cada solicitud; no existe ninguna ruta en la que una llamada estancada bloquee permanentemente un hilo de trabajo.
- Observabilidad — una línea de log por intento con el identificador del prompt, el número de intento, el estado y la latencia; cada resultado de solicitud en la salida por lotes es atribuible.
- Artefactos de fallo — guarda al menos una respuesta real correcta y una respuesta real de error como fixtures de prueba.
Si alguna casilla no está marcada, corregirlo ahora sale más barato que depurarlo a las dos de la mañana. Con la lista completamente en verde, tendrás un cliente pequeño, observable y escalable, en lugar de un script que da miedo tocar. Para la referencia autoritativa de parámetros y cualquier actualización de endpoints, guarda la documentación de HiAPI en favoritos y úsala como base definitiva.
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