Come si usa FLUX.3 Image API? La prima immagine in 5 minuti

TL;DR

• FLUX.3 Image è un modello di immagini rilasciato da Black Forest Labs nell'ottobre 2026, con nome del modello flux-3-image. Un unico nome del modello gestisce sia generazione da testo che modifica di immagini; per la modifica si possono inviare fino a 10 immagini di riferimento. Apri la pagina del modello per provarlo online.
• Fatturazione per immagine: 1K (predefinito) $0.048, 2K $0.10, 4K $0.607, con uno sconto del 20% su tutte le fasce fino al 31 ottobre. Ogni task produce 1 immagine.
• Il modo più rapido: invia POST /v1/tasks con prompt, esegui il polling fino a success, scarica output[0].url. Ricordati di specificare esplicitamente resolution e di controllare sia lo stato fail sia failed.

Cos'è FLUX.3 Image e cosa c'è di nuovo?

• Un unico nome del modello per generazione e modifica. Se non passi image_urls è generazione da testo; se passi 1–10 immagini di riferimento, modifichi intorno alle immagini di riferimento e nel prompt specifichi chiaramente cosa deve fornire ciascuna immagine.
• Cinque livelli di risoluzione: da 768 ($0.041) a 4K ($0.607); 15 formati da 21:9 a 9:21, più auto.
• La ricerca web integra i dettagli. grounding è attivo per impostazione predefinita: prima della generazione può cercare sul web e nelle immagini per integrare le informazioni della scena.
• Nono posto nella classifica text-to-image di Artificial Analysis.

Interno a 1.5K, 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.

Genera con questo prompt → (1.5K, 3:2)

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

Due percorsi per iniziare

Prova online (senza scrivere codice):

1. Apri la pagina del modello FLUX.3 Image e accedi (i nuovi utenti ricevono 200 crediti alla registrazione).
2. Incolla il prompt, scegli risoluzione e formato e, se necessario, carica immagini di riferimento.
3. Fai clic su genera e scarica il risultato.

Chiamata API:

1. Crea una API Key nella console.
2. POST /v1/tasks, "model": "flux-3-image".
3. Esegui il polling di GET /v1/tasks/{taskId} o ricevi il callback, quindi salva output[0].url.

curl: la prima immagine

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 risposta contiene data.taskId. Esegui il polling di GET /v1/tasks/{taskId} e, quando status diventa success, scarica output[0].url.

Python: invio, polling, download

# pip install requests; export HIAPI_KEY=你的 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):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    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]  # 按返回的文件类型保存
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

Modifica con immagini di riferimento

Invia image_urls (1–10 link pubblici) e nel prompt specifica cosa fornisce ciascuna immagine e cosa non deve essere ripreso. L'esempio qui sotto è una composizione di tre immagini: l'immagine 1 fornisce il soggetto, l'immagine 2 fornisce la scena, l'immagine 3 serve solo per la palette colori.

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",   # 图 1：主体
        "https://your-cdn.example.com/cabin.jpg",    # 图 2：场景
        "https://your-cdn.example.com/street.jpg",   # 图 3：只借配色
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image, tre immagini di riferimento, 3:2, $0.048. Le immagini di riferimento non hanno sovrapprezzo.

Parametri in breve

Campo	Valori	Descrizione
prompt	stringa, obbligatorio, massimo 5000 caratteri	Descrivi la scena oppure specifica cosa modificare e cosa mantenere
image_urls	1–10 link pubblici, opzionale	Se non lo passi, è generazione da testo
resolution	768 / 1K / 1.5K / 2K / 4K, predefinito 1K	Determina il prezzo; larghezza e altezza effettive variano con il formato
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, predefinito auto	Per posizioni fisse, scegli esplicitamente il rapporto
safety_tolerance	0–4, predefinito 2	0 è il più rigoroso
grounding	booleano, predefinito true	Cerca sul web e nelle immagini prima della generazione

Da tenere presente prima della messa in produzione

• Specifica sempre resolution. Un errore di battitura su 4K fa passare un'immagine da $0.048 a $0.607.
• Controlla sia fail sia failed. La documentazione indica failed, ma controllare entrambi è più sicuro.
• Usa i callback invece del polling: aggiungi allo stesso livello di input "callback": {"url": "https://your-app.example.com/hiapi/callback"} e deduplica per taskId.
• Salva subito i risultati. output[0].url ha una scadenza: scarica tempestivamente oppure scegli l'archiviazione permanente quando crei il task.
• Includi l'header Idempotency-Key: nei retry, la stessa Key crea il task una sola volta.

Domande frequenti

Quante immagini produce un task?

1. Per più direzioni, invia task separati.

Si può scegliere PNG o JPEG?

Questo modello non offre la scelta del formato. Se serve un formato specifico, converti dopo il download.

Quando disattivare la ricerca web?

Quando hai già le tue immagini di riferimento e la direzione creativa è definita. Scrivi grounding: false; il prezzo non cambia.

Se la generazione fallisce, viene addebitato qualcosa?

No. Il costo si applica solo quando l'immagine viene generata con successo.

I prezzi delle varie fasce sono in Prezzi di FLUX.3 Image API, altri prompt in Esempi di prompt per FLUX.3 Image, e il confronto con la generazione precedente usando lo stesso prompt in FLUX.3 Image vs FLUX.2. Puoi anche andare direttamente alla pagina del modello per generare questa baita in cedro.