---

slug: flux-2-klein-4b-text-to-image-api-guide locale: en title: Cómo usar flux-2-klein-4b/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-4b/text-to-image a través del endpoint unificado /v1/tasks de hiapi.
• 'Tabla completa de parámetros: prompt, valores de enumeración de aspect_ratio y seed — un schema estricto rechazará campos desconocidos.'
• 'Consideraciones para producción: elegir entre callback.url y el sondeo, la cabecera Idempotency-Key y las dos estructuras de respuesta de error.' takeaways:
• Crea una tarea con POST /v1/tasks y luego consulta GET /v1/tasks/{taskId}, o usa callback.url para recibir el resultado.
• aspect_ratio admite 11 proporciones con nombre; 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 en caso de timeout.
• Los errores 400 usan error_code; los errores 401 de autenticación 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-4b meta_description: 'Llamar a flux-2-klein-4b/text-to-image con curl y Python: crear tareas, consultar para obtener la imagen y gestionar callbacks, idempotencia y errores en producción.' keywords:
• api de texto a imagen flux-2-klein-4b
• ejemplo de api de flux-2-klein-4b
• api de generación de imágenes hiapi
• api de flux 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-4b/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-4b/text-to-image, espera a que se genere la imagen y luego la descarga — además de los detalles de producción que debes conocer antes de ejecutarlo de forma desatendida (callbacks, idempotencia, estructuras de error).

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

Ejemplo mínimo funcional

Los modelos generativos 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 consultas 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-4b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

Resultado devuelto:

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

Consulta 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.jpg", "expireAt": 1785939579}
    ]
  },
  "message": "success"
}

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

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-4b/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.jpg", "wb").write(image_bytes)

Parámetros importantes

flux-2-klein-4b/text-to-image usa 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 los valores: 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21. Si se omite, el valor predeterminado es 1:1.
seed	No	Entero. Reutilizar el mismo seed hace que los resultados de varias llamadas sean reproducibles.

Consulta la referencia completa de parámetros en la página del modelo; el precio actual por imagen está en la página de precios — guíate por ella en lugar de codificar cifras fijas, ya que los precios de facturación por uso cambian.

Notas para producción

Usa callbacks en lugar de sondeo. Salvo en scripts rápidos, 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 — cuando la tarea termine, hiapi enviará el resultado por POST a tu endpoint, con una estructura de payload idéntica a la que devuelve GET /v1/tasks/{taskId}. Para detalles sobre los campos de callback y la verificación de firmas, consulta Crear tarea.

{
  "model": "flux-2-klein-4b/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 key en la misma cuenta no crea una segunda tarea — recuperas el taskId original. Por eso es seguro reintentar solicitudes que expiraron de tu lado sin duplicar el cobro.

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

• Un input incorrecto (falta prompt, aspect_ratio fuera de rango, campos no admitidos) devuelve HTTP 400 con el cuerpo {"error_code": "INVALID_REQUEST", "message": "..."}.
• Una API key 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 — la referencia completa de sondeo
• Autenticación — ámbitos de la API key y formato de la cabecera
• flux-2-klein-4b/image-to-image — la misma familia, para editar una imagen de entrada en lugar de generar desde cero
• flux-2-klein-9b/text-to-image — un modelo más grande de la misma familia klein

Preguntas frecuentes

¿flux-2-klein-4b/text-to-image admite imagen a imagen? No directamente — eso es otro modelo, flux-2-klein-4b/image-to-image, con su propio schema de entrada.

¿Cuál es la diferencia entre flux-2-klein-4b y flux-2-klein-9b? Ambos son endpoints de texto a imagen de la misma familia FLUX.2 [klein]; 9b es el más grande de los dos. Antes de cambiar, consulta la página del modelo 9b 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 ningún campo de cantidad. Hay que enviar una solicitud por cada imagen.

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

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

¿Hace falta ejecutar un servidor propio para usar esta API? Solo si necesitas callbacks. Consultar GET /v1/tasks/{taskId} desde un script, una tarea cron o una función serverless es totalmente viable en escenarios de bajo tráfico; cuando el volumen de generación crezca, cambia a callback.url.