¿Cómo usar la API de texto a imagen de FLUX.2? Parámetros, código y una imagen real generada

TL;DR

• El modelo de texto a imagen FLUX.2 Pro en HiAPI se llama flux-2/text-to-image, creado por Black Forest Labs; su punto fuerte es el seguimiento de instrucciones y el texto dentro de la imagen. Abre la página del modelo y pruébalo online.
• Facturación por tramo de resolución: 0.5 MP $0.0375, 1 MP (por defecto) $0.05, 2 MP $0.075, 4 MP $0.125. La relación de aspecto no afecta al precio.
• La forma más rápida: POST /v1/tasks con prompt, haz polling hasta success y descarga output[0].url. El valor de resolution lleva un espacio en medio; debe escribirse "1 MP".

Primero, una imagen real generada

La siguiente imagen se generó con la petición del artículo, 2 MP, 16:9:

A wide overhead flat-lay of a modern developer desk: a matte black mechanical
keyboard on the left, a ceramic mug of steaming coffee on the right, a small
potted succulent in the top corner, and an open spiral notebook in the center
with the handwritten words 'API ready' clearly visible on the page, soft
natural window light falling from the left, a muted teal and warm wood color
palette, no other text or logos anywhere in the frame

Generar con este prompt → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0.075. El «API ready» del cuaderno está bien escrito y no hay texto de más en la imagen.

Consulta rápida de parámetros

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Cadena	Pon los elementos importantes al principio de la frase; con 30–80 palabras en inglés se obtiene el mejor resultado
aspect_ratio	No	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, por defecto 1:1	Si eliges custom, se usa junto con width / height
resolution	No	0.5 MP / 1 MP / 2 MP / 4 MP, por defecto 1 MP	Determina el precio; se ignora con custom
width / height	Solo custom	256–2048	Se redondea automáticamente a múltiplos de 16
output_format	No	webp (por defecto) / jpg / png
output_quality	No	0–100, por defecto 80	Solo se aplica a webp y jpg
seed	No	Entero	Si se fija, permite reproducir el mismo resultado
safety_tolerance	No	1–5, por defecto 2	1 es el más estricto

Los parámetros se validan de forma estricta: si envías un campo que no está en la documentación, se devuelve directamente HTTP 400 (additional properties ... not allowed). Esta entrada solo acepta texto; para editar imágenes con imágenes de referencia, usa flux-2/image-to-image.

curl: genera la primera imagen

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A matte charcoal coffee bag on a rustic oak counter, kraft paper label reading DAYBREAK ROAST, warm morning window light",
      "aspect_ratio": "4:3",
      "resolution": "1 MP",
      "output_format": "png"
    }
  }'

La respuesta solo contiene data.taskId; la imagen aún no está generada. Haz polling a GET /v1/tasks/{taskId} y, cuando status pase a success, descárgala desde output[0].url.

Python: enviar, hacer polling y descargar

# pip install requests; export HIAPI_KEY=tu Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # Al reintentar el mismo envío, reutiliza el mismo Idempotency-Key; solo se cobrará una vez
    r = requests.post(API, json={"model": "flux-2/text-to-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A wide overhead flat-lay of a modern developer desk, an open notebook with the handwritten words 'API ready', soft window light",
    aspect_ratio="16:9", resolution="2 MP", output_format="png", seed=42,
)
with open("desk.png", "wb") as f:
    f.write(requests.get(url).content)

Cuánto cuesta

Resolución	Por imagen	100 imágenes
0.5 MP	$0.0375	$3.75
1 MP (por defecto)	$0.05	$5.00
2 MP	$0.075	$7.50
4 MP	$0.125	$12.50

Precio actual de HiAPI, verificado el 18 de octubre de 2026.

La relación de aspecto, seed y el formato de salida no afectan al precio; solo cuenta el tramo de resolución. Los fallos no se cobran. Si quieres gastar menos, FLUX.2 [klein] 4B 1 MP cuesta $0.00143 por imagen; consulta la comparativa de tramos en Precios de la API de FLUX.2.

Atención antes de lanzar a producción

• resolution lleva un espacio en medio: escribe "1 MP", no "1MP" ni "1K"; si lo escribes mal, se devuelve 400 y se listan los valores válidos.
• Con tamaño custom se ignora resolution: cuando aspect_ratio es custom, la imagen se genera según width × height.
• Para reproducir, fija seed: con el mismo prompt y el mismo seed, el resultado es muy consistente, lo que facilita comparar al ajustar la redacción.
• Guarda el resultado de inmediato: output[0].url tiene caducidad; descárgala y guárdala en tu propio almacenamiento.
• Usa callbacks en lugar de polling: añade al mismo nivel que input "callback": {"url": "https://your-app.example.com/hiapi/callback"} y deduplica por taskId.

Preguntas frecuentes

¿Es obligatorio escribir resolution?

No, por defecto es 1 MP. Pero se recomienda escribirlo siempre para no confundirlo con 4 MP.

¿Se puede enviar una imagen de referencia?

Esta entrada no. Para editar imágenes con referencias o combinar varias imágenes, usa flux-2/image-to-image, con hasta 8 imágenes de referencia; consulta prompts listos en Prompts de edición de FLUX.2.

¿Por qué devuelve «additional properties not allowed»?

Porque enviaste un campo que este modelo no tiene, como strength o prompt_upsampling. Usa solo los campos de la tabla de parámetros anterior.

¿Cómo elegir entre este y FLUX.3 Image?

FLUX.3 Image usa un solo nombre de modelo tanto para generar como para editar, puede generar en 4K y admite hasta 10 imágenes de referencia; FLUX.2 Pro tiene seed y ancho/alto personalizados, y 4 MP cuesta solo $0.125. Consulta la comparativa con el mismo prompt en FLUX.3 Image vs FLUX.2.

Copia el prompt del escritorio de arriba y ve a la página del modelo para generar la primera.