Come si usa l'API text-to-image di FLUX.2? Parametri, codice e un'immagine reale

TL;DR

• Il nome del modello text-to-image FLUX.2 Pro su HiAPI è flux-2/text-to-image, prodotto da Black Forest Labs; i suoi punti di forza sono la fedeltà al prompt e il testo all'interno dell'immagine. Apri la pagina del modello per provarlo online.
• Fatturazione a fasce di risoluzione: 0,5 MP $0,0375, 1 MP (predefinito) $0,05, 2 MP $0,075, 4 MP $0,125. Le proporzioni non influenzano il prezzo.
• Il modo più rapido: POST /v1/tasks con prompt, fai polling finché lo stato è success, scarica output[0].url. Il valore di resolution contiene uno spazio, va scritto come "1 MP".

Prima guarda un'immagine reale

Questa è stata generata con la richiesta di questo articolo, 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

Genera con questo prompt → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0,075. Il «API ready» sul quaderno è scritto correttamente e nell'immagine non ci sono altri testi superflui.

Riferimento rapido dei parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	stringa	Metti gli elementi importanti all'inizio; 30–80 parole in inglese danno i risultati migliori
aspect_ratio	No	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, predefinito 1:1	Con custom usa width / height
resolution	No	0.5 MP / 1 MP / 2 MP / 4 MP, predefinito 1 MP	Determina il prezzo; ignorato con custom
width / height	Solo con custom	256–2048	Arrotondato automaticamente a un multiplo di 16
output_format	No	webp (predefinito) / jpg / png
output_quality	No	0–100, predefinito 80	Ha effetto solo su webp e jpg
seed	No	intero	Fissandolo si riproduce lo stesso risultato
safety_tolerance	No	1–5, predefinito 2	1 è il più restrittivo

I parametri sono validati in modo rigoroso: se invii un campo in più non presente nella documentazione, viene restituito direttamente HTTP 400 (additional properties ... not allowed). Questo endpoint accetta solo testo; per modificare un'immagine con un'immagine di riferimento usa flux-2/image-to-image.

curl: genera la prima immagine

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 risposta contiene solo data.taskId, l'immagine non è ancora pronta. Fai polling su GET /v1/tasks/{taskId} e, quando status diventa success, scarica da 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-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)

Quanto costa

Risoluzione	Per immagine	100 immagini
0.5 MP	$0,0375	$3,75
1 MP (predefinito)	$0,05	$5,00
2 MP	$0,075	$7,50
4 MP	$0,125	$12,50

Prezzi attuali di HiAPI, verificati il 18 ottobre 2026.

Proporzioni, seed e formato di output non influenzano il prezzo: conta solo la fascia di risoluzione. In caso di errore non viene addebitato nulla. Per spendere meno, FLUX.2 [klein] 4B a 1 MP costa $0,00143 per immagine; il confronto tra le fasce è in Prezzi dell'API FLUX.2.

Note prima del go-live

• resolution contiene uno spazio: scrivi "1 MP", non "1MP" o "1K"; se sbagli, viene restituito 400 con l'elenco dei valori ammessi.
• Con dimensioni custom, resolution viene ignorato: quando aspect_ratio è custom, l'immagine viene generata in base a width × height.
• Per riprodurre fissa il seed: con lo stesso prompt e lo stesso seed il risultato è molto simile, utile per confrontare varianti della formulazione.
• Salva subito il risultato: output[0].url ha una scadenza; dopo il download archivialo nel tuo storage.
• Usa il callback al posto del polling: allo stesso livello di input aggiungi "callback": {"url": "https://your-app.example.com/hiapi/callback"} e deduplica in base al taskId.

Domande frequenti

resolution è obbligatorio?

No, il predefinito è 1 MP. Però conviene scriverlo ogni volta, per non confonderlo con 4 MP.

Si può inviare un'immagine di riferimento?

Questo endpoint no. Per modificare un'immagine con un riferimento o comporre più immagini usa flux-2/image-to-image, fino a 8 immagini di riferimento; i prompt pronti sono in Prompt per la modifica immagini FLUX.2.

Perché viene restituito «additional properties not allowed»?

Hai inviato un campo che questo modello non supporta, ad esempio strength o prompt_upsampling. Usa solo i campi della tabella dei parametri qui sopra.

Come scegliere tra questo e FLUX.3 Image?

FLUX.3 Image con un solo nome di modello genera e modifica immagini, arriva a 4K e supporta fino a 10 immagini di riferimento; FLUX.2 Pro ha seed e larghezza/altezza personalizzate, e 4 MP costa solo $0,125. Il confronto con lo stesso prompt è in FLUX.3 Image vs FLUX.2.

Copia il prompt della scrivania qui sopra e vai alla pagina del modello e genera la tua prima immagine.