¿Cómo usar la API de FLUX.3 Image? Genera tu primera imagen en 5 minutos

TL;DR

• FLUX.3 Image es un modelo de imágenes publicado por Black Forest Labs en octubre de 2026, con el nombre de modelo flux-3-image. Un solo nombre de modelo cubre tanto la generación de texto a imagen como la edición de imágenes, y la edición admite hasta 10 imágenes de referencia. Abre la página del modelo y pruébalo en línea.
• Facturación por imagen: 1K (predeterminado) $0.048, 2K $0.10, 4K $0.607; 20 % de descuento en todas las tarifas hasta el 31 de octubre. Cada tarea genera 1 imagen.
• La forma más rápida de llamarlo: POST /v1/tasks con prompt, consulta hasta obtener success y descarga output[0].url. Recuerda indicar resolution de forma explícita y comprobar tanto el estado fail como failed.

¿Qué es FLUX.3 Image y qué hay de nuevo?

• Generación y edición con un solo nombre de modelo. Si no pasas image_urls, es texto a imagen; si pasas de 1 a 10 imágenes de referencia, edita en torno a ellas, y en el prompt debes indicar claramente qué aporta cada imagen.
• Cinco niveles de resolución: de 768 ($0.041) a 4K ($0.607); 15 relaciones de aspecto de 21:9 a 9:21, además de auto.
• Búsqueda web para añadir detalles. grounding está activado por defecto; antes de generar puede buscar en la web y en imágenes para complementar la información visual.
• Puesto 9 en la clasificación de texto a imagen de Artificial Analysis.

Imagen de interior en 1.5K y 3:2:

Architectural interior photograph of a cedar alpine reading cabin,
floor-to-ceiling window opening onto a misty mountain lake, linen armchair and a
small brass lamp, warm wood grain, quiet morning atmosphere, restrained
Scandinavian design, no text.

Generar con este prompt → (1.5K, 3:2)

flux-3-image, 1.5K, 3:2, $0.07.

Dos vías para empezar

Prueba en línea (sin escribir código):

1. Abre la página del modelo FLUX.3 Image e inicia sesión (los nuevos usuarios reciben 200 créditos al registrarse).
2. Pega el prompt, elige la resolución y la relación de aspecto y, si lo necesitas, sube imágenes de referencia.
3. Haz clic en generar y descarga el resultado.

Llamada a la API:

1. Crea una API Key en la consola.
2. POST /v1/tasks, "model": "flux-3-image".
3. Consulta GET /v1/tasks/{taskId} o recibe el callback y guarda output[0].url.

curl: genera la primera imagen

1K, 4:3, $0.048:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "input": {
      "prompt": "A refined still life of a terracotta architectural model on ivory paper, brass desk lamp, olive leaves, soft late-afternoon sunlight, no text",
      "resolution": "1K",
      "aspect_ratio": "4:3"
    }
  }'

La respuesta incluye data.taskId. Consulta GET /v1/tasks/{taskId} y, cuando status pase a success, descarga output[0].url.

Python: enviar, consultar 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 cobra una vez
    r = requests.post(API, json={"model": "flux-3-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 cinematic rainy Tokyo side street at blue hour, a small bookstore with warm amber windows, a red bicycle outside, no readable signs",
    resolution="2K", aspect_ratio="16:9",
)
ext = url.split("?")[0].rsplit(".", 1)[-1]  # guarda según el tipo de archivo devuelto
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

Editar con imágenes de referencia

Pasa image_urls (de 1 a 10 enlaces públicos) y en el prompt indica claramente qué aporta cada imagen y qué no debe incorporar. La siguiente composición usa tres imágenes: la imagen 1 aporta el sujeto, la imagen 2 el escenario y la imagen 3 solo la paleta de colores.

Create a refined product photograph. Use the cobalt blue ceramic teapot and
walnut handle from Image 1 as the main subject, place it on a pale stone side
table inside the cedar reading cabin from Image 2. Borrow only the subtle teal
and amber lighting palette from Image 3. Preserve the teapot shape and glaze,
keep the lake window visible in the background, realistic scale, no lettering.

url = generate(
    prompt=open("teapot_prompt.txt").read(),
    image_urls=[
        "https://your-cdn.example.com/teapot.jpg",   # Imagen 1: sujeto
        "https://your-cdn.example.com/cabin.jpg",    # Imagen 2: escenario
        "https://your-cdn.example.com/street.jpg",   # Imagen 3: solo la paleta de colores
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image, tres imágenes de referencia, 3:2, $0.048. Las imágenes de referencia no tienen coste adicional.

Referencia rápida de parámetros

Campo	Valores	Descripción
prompt	cadena, obligatorio, máximo 5000 caracteres	Describe la imagen o indica claramente qué cambiar y qué conservar
image_urls	de 1 a 10 enlaces públicos, opcional	Si no se pasa, es texto a imagen
resolution	768 / 1K / 1.5K / 2K / 4K, por defecto 1K	Determina el precio; el ancho y alto reales varían según la relación de aspecto
aspect_ratio	21:9 2:1 16:9 3:2 7:5 4:3 5:4 1:1 4:5 3:4 5:7 2:3 9:16 1:2 9:21 auto, por defecto auto	Para posiciones fijas, elige una relación explícita
safety_tolerance	0–4, por defecto 2	0 es el más estricto
grounding	booleano, por defecto true	Busca en la web y en imágenes antes de generar

Aspectos a tener en cuenta antes de publicar

• Escribe siempre resolution. Si por error pones 4K, una imagen pasa de $0.048 a $0.607.
• Comprueba tanto fail como failed. La documentación indica failed, pero comprobar ambos es más seguro.
• Usa callbacks en lugar de polling: añade "callback": {"url": "https://your-app.example.com/hiapi/callback"} al mismo nivel que input y deduplica por taskId.
• Guarda el resultado de inmediato. output[0].url tiene una validez limitada; descárgalo a tiempo o elige almacenamiento permanente al crear la tarea.
• Incluye la cabecera Idempotency-Key: al reintentar, la misma Key solo crea la tarea una vez.

Preguntas frecuentes

¿Cuántas imágenes genera una tarea?

1. Si quieres varias variantes, envía tareas por separado.

¿Se puede elegir PNG o JPEG?

Este modelo no ofrece selección de formato. Si necesitas un formato específico, conviértelo después de descargar.

¿Cuándo desactivar la búsqueda web?

Cuando ya tengas tus propias imágenes de referencia y la dirección creativa esté definida. Escribe grounding: false; el precio no cambia.

¿Se cobra si la generación falla?

No. Solo se factura cuando la imagen se genera correctamente.

Consulta los precios de cada nivel en Precios de la API de FLUX.3 Image, más prompts en Ejemplos de prompts de FLUX.3 Image, y la comparación con el mismo prompt frente a la generación anterior en FLUX.3 Image vs FLUX.2. También puedes ir a la página del modelo para generar esta cabaña de cedro.