---

slug: flux-2-klein-9b-text-to-image-api-guide locale: en title: Cómo usar flux-2-klein-9b/text-to-image a través de la API de hiapi category: tutorial summary:

• Ejemplos mínimos en curl y Python para llamar a flux-2-klein-9b/text-to-image mediante el endpoint unificado /v1/tasks de hiapi.
• 'Tabla completa de parámetros: prompt, aspect_ratio, num_inference_steps, output_format y seed; un schema estricto rechaza los campos desconocidos.'
• 'Consideraciones para producción: callback.url frente al sondeo, la cabecera Idempotency-Key y las dos estructuras de respuesta de error. takeaways:
• Crea una tarea con POST /v1/tasks y luego sondea GET /v1/tasks/{taskId} o usa callback.url para obtener el resultado.
• num_inference_steps solo acepta 4-8 (entero); este modelo no tiene los campos size ni n.
• Al reintentar con la misma cabecera Idempotency-Key se devuelve el mismo taskId; es seguro reutilizarla tras un timeout.
• Los errores 400 usan error_code y los errores de autenticación 401 usan el error.code anidado; comprueba primero el código de estado HTTP. meta_title: Guía de la API de texto a imagen de flux-2-klein-9b meta_description: Llama a flux-2-klein-9b/text-to-image con curl y Python; crea tareas, sondea la imagen y gestiona callbacks, idempotencia y errores en producción. keywords:
• api de texto a imagen flux-2-klein-9b
• ejemplo de api de flux-2-klein-9b
• api de generación de imágenes hiapi
• flux klein api curl python tags:
• api-guide
• image-generation
• flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

---

Cómo usar flux-2-klein-9b/text-to-image a través de la API de hiapi

Qué vas a construir

Un script que envía un prompt a flux-2-klein-9b/text-to-image, espera a que la imagen se genere y la descarga; además, se incluyen los detalles de producción que necesitas antes de ejecutarlo de forma desatendida (callbacks, idempotencia, estructura de errores).

Requisitos previos: obtén una clave de API desde la consola de hiapi. Todas las solicitudes siguientes se autentican con Authorization: Bearer sk-<your-api-key>.

Ejemplo mínimo funcional

Los modelos de generación de hiapi se ejecutan detrás de un endpoint asíncrono unificado: POST /v1/tasks crea una tarea y devuelve inmediatamente un taskId; después sondeas GET /v1/tasks/{taskId} hasta que alcanza un estado terminal.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

Respuesta devuelta:

{"code": 200, "data": {"taskId": "tk-hiapi-01K..."}, "message": "success"}

Sondea la misma tarea hasta que data.status pase de handling a success (pasando brevemente por archiving):

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01K... \
  -H "Authorization: Bearer sk-<your-api-key>"

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.png", "expireAt": 1785941465}
    ]
  },
  "message": "success"
}

data.output[0].url es la imagen generada. Es un enlace temporal; en las pruebas caduca unos 7 días después de la generación; por lo tanto, descarga los bytes y guárdalos por tu cuenta en lugar de enlazar directamente a él.

El mismo flujo en Python (con sondeo)

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.png", "wb").write(image_bytes)

Parámetros importantes

flux-2-klein-9b/text-to-image tiene un schema de entrada estricto: enviar campos que no reconoce (size, n, negative_prompt o cualquier otro campo que acepten otros modelos de imagen de hiapi) se rechaza directamente, así que no copies parámetros entre modelos sin consultar antes la página del modelo.

Campo	¿Obligatorio?	Descripción
prompt	Sí	Cadena que describe la imagen.
aspect_ratio	No	Uno de 1:1, 4:3, 3:4, 16:9, 9:16. Si se omite, el valor predeterminado es 4:3.
num_inference_steps	No	Entero, 4–8. Valor predeterminado 4; valores más altos cambian velocidad por algo más de detalle.
output_format	No	Uno de jpeg, png, webp. Valor predeterminado png.
seed	No	Entero. Reutilizar el seed hace que los resultados de varias llamadas sean reproducibles.

Consulta la referencia completa de parámetros en la página del modelo; para el precio actual de facturación por imagen, consulta la página de precios: revísalo allí en lugar de codificar cifras fijas, ya que las tarifas basadas en el uso cambian.

Consideraciones para producción

Usa callbacks en lugar de sondeo. Para cualquier caso que vaya más allá de un script rápido, omite el bucle de sondeo y añade callback.url (y "when": "final") en el cuerpo de la solicitud de creación de la tarea; hiapi enviará el resultado por POST a tu endpoint cuando la tarea finalice, con una carga útil idéntica a la que devuelve GET /v1/tasks/{taskId}. Para más detalles sobre los campos de callback y la verificación de firmas, consulta Crear tarea.

{
  "model": "flux-2-klein-9b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

Idempotencia. Establece la cabecera Idempotency-Key en las llamadas a POST /v1/tasks (máximo 255 bytes). Reintentar la misma solicitud con la misma clave bajo la misma cuenta no crea una segunda tarea: recuperas el taskId original. Esta es precisamente la razón por la que es seguro reintentar solicitudes que se agotaron por timeout en tu lado sin facturarlas dos veces.

Gestión de errores. En la práctica aparecen dos estructuras de fallo distintas, así que comprueba ambas:

• Un input incorrecto (prompt ausente, num_inference_steps fuera de rango, campos no admitidos) devuelve HTTP 400 y {"error_code": "INVALID_REQUEST", "message": "..."}.
• Una clave de API no válida o no autorizada devuelve HTTP 401 con una estructura de respuesta diferente: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

Ramifica primero según el código de estado HTTP y luego lee el campo de error que realmente exista: no asumas que todos los fallos usan la misma estructura de respuesta.

Recursos relacionados

• Obtener detalles de la tarea: referencia completa del sondeo
• Autenticación: alcances de la clave de API y formato de las cabeceras
• flux-2-klein-9b/image-to-image: la misma familia, edita una imagen de entrada en lugar de generar desde cero
• flux-2-klein-4b/text-to-image: un modelo más pequeño y rápido dentro de la misma familia klein

Preguntas frecuentes

¿flux-2-klein-9b/text-to-image admite imagen a imagen? No directamente: ese es un modelo aparte, flux-2-klein-9b/image-to-image, con su propio schema de entrada.

¿Cuál es la diferencia entre flux-2-klein-9b y flux-2-klein-4b? Ambos son endpoints de texto a imagen de la misma familia FLUX.2 [klein]; 9b es el mayor de los dos y está pensado para lograr un mayor realismo, mejor renderizado de texto y más detalle. Antes de cambiar, consulta la página del modelo 4b para conocer su precio y parámetros actuales.

¿Se pueden solicitar varias imágenes en una sola llamada? No: el schema no acepta n ni campos de recuento. Envía una solicitud por imagen.

¿Cuánto dura la URL de la imagen devuelta? output[0].url es un enlace temporal con su propia marca de tiempo expireAt; trátalo como de corta duración (alrededor de una semana en las pruebas) y descarga los bytes en cuanto la tarea tenga éxito, en lugar de almacenar la URL.

¿Por qué recibo un error 401 permission_denied? Tu clave falta, no es válida o no tiene permiso para acceder a este modelo. Confirma que envías Authorization: Bearer sk-... con la clave de la consola, no con el marcador de posición.

¿Es necesario ejecutar mi propio servidor para usar esta API? Solo si necesitas callbacks. Sondear GET /v1/tasks/{taskId} desde un script, una tarea programada o una función serverless funciona perfectamente para usos de bajo volumen; cuando el volumen de generación crezca, cambia a callback.url.