Come usare l'API FLUX.1 Kontext Max? Genera la tua prima immagine in 5 minuti

TL;DR

• Cos'è: FLUX.1 Kontext Max di Black Forest Labs. Generazione da testo e modifica di una singola immagine condividono lo stesso ID modello. È ora disponibile su HiAPI: apri la pagina del modello, inserisci il prompt e genera. I nuovi utenti ricevono 200 crediti alla registrazione, pari a circa 1,4 immagini.
• Quanto costa: $0,0715 per immagine (143 crediti), stesso prezzo per generazione da testo e modifica. Con $10 puoi generare circa 139 immagini; i crediti delle attività fallite vengono rimborsati.
• Come chiamare l'API: POST https://api.hiapi.ai/v1/tasks, imposta model a flux-1-kontext-max. Dopo aver ottenuto il taskId, esegui il polling o attendi il callback, quindi scarica il risultato da data.output[0].url.

Da quando FLUX.1 Kontext Max è disponibile, le domande più frequenti sono due: se è possibile modificare solo una parte dell'immagine e quanto tempo serve per integrarlo nel proprio prodotto. Prima vediamo le capacità, poi seguiamo due percorsi di avvio.

Cos'è FLUX.1 Kontext Max e cosa c'è di nuovo?

• Un solo ID modello per due tipi di attività. Se non passi un'immagine in input, è generazione da testo; se passi input_image, è modifica. Il codice non deve essere diviso in due versioni.
• La modifica segue il principio "cosa cambiare, cosa mantenere". Puoi modificare materiali e stile, aggiungere o rimuovere elementi, colori e illuminazione, testo nell'immagine; le parti non menzionate nel prompt vengono mantenute il più possibile invariate.
• Sei formati e, in modifica, puoi mantenere le proporzioni originali. aspect_ratio può essere 21:9, 16:9, 4:3, 1:1, 3:4, 9:16; in modifica, se lo lasci vuoto, l'output mantiene le proporzioni dell'immagine originale, con pixel arrotondati a multipli di 32: 1280×720 diventa 1328×752.
• Output in jpeg o png, circa 1 milione di pixel per immagine. prompt ha un limite di 4.000 caratteri; i prompt in cinese vengono tradotti automaticamente in inglese prima della generazione.

Generazione da testo, 16:9. Il prompt completo è quello nel curl qui sotto, puoi copiarlo così com'è.

Genera con questo prompt →

Due percorsi di avvio: prova online o API?

Per vedere prima il risultato, prova online; per integrare nel prodotto, usa l'API. Entrambi i percorsi usano lo stesso modello e gli stessi prezzi.

Prova online (circa 1 minuto)

1. Apri la pagina del modello FLUX.1 Kontext Max, oppure clicca il link sotto l'immagine qui sopra: il prompt verrà compilato automaticamente.
2. Registrati o accedi: i nuovi account ricevono 200 crediti.
3. Seleziona 16:9 e clicca Genera.
4. Se il risultato ti soddisfa, scaricalo; per modificare l'immagine, carica l'originale nella stessa pagina e scrivi il prompt di modifica.

Integrazione API (circa 5 minuti)

1. Crea una API Key (sk-...) nella console HiAPI.
2. POST /v1/tasks per creare l'attività; nella risposta ricevi data.taskId.
3. Usa GET /v1/tasks/{taskId} per interrogare lo stato o attendi la notifica callback.url; quando data.status diventa success, scarica l'immagine da data.output[0].url.

$0,0715 per immagine, con $10 circa 139 immagini: abbastanza per ottimizzare il prompt fino a soddisfazione. Parametri completi nella documentazione in cinese.

Prima immagine: versione curl

Creazione dell'attività:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
      "aspect_ratio": "16:9",
      "output_format": "jpeg",
      "prompt_upsampling": false
    }
  }'

L'ID attività restituito è in data.taskId:

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

Interrogazione del risultato:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Solo prompt è obbligatorio. output_format è jpeg per impostazione predefinita, prompt_upsampling è disattivato per impostazione predefinita, safety_tolerance è 2 per impostazione predefinita (0 è il più rigoroso).

Prima immagine: versione Python

Creazione, polling e download in un unico script: basta sostituire la tua Key per eseguirlo:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
        "aspect_ratio": "16:9",
    },
}

task_id = requests.post(API, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    image_url = data["output"][0]["url"]
    with open("flux-1-kontext-max.jpg", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(data.get("error"))

Modalità modifica: basta aggiungere input_image

Aggiungi input_image in input e la stessa richiesta passa da generazione da testo a modifica. Di seguito, usando l'immagine dell'angolo lettura come originale, sostituiamo solo la poltrona e aggiungiamo una lampada da terra:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "Change the linen armchair to a deep forest-green velvet armchair, add a slim brass floor lamp beside it, and keep the window, books, cup, table and afternoon light unchanged.",
      "input_image": "https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg"
    }
  }'

input_image accetta l'URL di un'immagine accessibile pubblicamente. In modifica, se non specifichi aspect_ratio, l'output mantiene le proporzioni dell'originale; per fondere più immagini, scegli la modifica immagini di GPT Image 2, che supporta da 1 a 16 immagini di riferimento.

Come scrivere il prompt di modifica: prima cosa cambiare, poi cosa mantenere

1. Scrivi la modifica come un'istruzione chiara. Specifica oggetto e nuovo stato: sostituisci linen armchair con deep forest-green velvet armchair.
2. Elenca uno per uno gli elementi da mantenere. Finestra, libri, tazza, tavolo, luce pomeridiana: scrivi ciò che ti interessa dell'originale e chiudi con keep ... unchanged.
3. Le modifiche correlate possono stare in una sola frase. Sostituire la poltrona e aggiungere una lampada da terra in ottone vengono gestiti insieme dal modello; le modifiche non correlate vanno inviate separatamente per verificare meglio i risultati.
4. Quando modifichi il testo nell'immagine, mantieni anche l'impaginazione. Ad esempio, cambiando KYOTO in OSAKA su un poster, specifica che layout, spazi bianchi e stile del carattere restano invariati.
5. Puoi scrivere direttamente in cinese. Il sistema traduce prima in inglese e poi genera; mantieni il prompt entro 4.000 caratteri.

4 cose da sapere prima del lancio

1. Usa i callback lato server. Aggiungi "callback": {"url": "https://yourapp.com/webhook", "when": "final"} nel corpo della richiesta: riceverai una notifica automatica allo stato finale, evitando il polling.
2. Non ripetere la POST in caso di timeout. Ogni creazione genera una nuova attività e viene addebitata separatamente; salva prima il taskId e deduplica nel tuo sistema prima di riprovare.
3. I link ai risultati scadono. data.output[0].url è un link temporaneo: scarica subito e salva nel tuo storage.
4. I pixel sono allineati a multipli di 32. In modifica, lasciando vuoto aspect_ratio, le proporzioni originali restano invariate e i pixel vengono arrotondati a multipli di 32: 1280×720 produce 1328×752; specificando un rapporto, l'immagine viene ritagliata o estesa a quel rapporto.

Domande frequenti

Bisogna cambiare modello tra generazione da testo e modifica? No. È sempre lo stesso flux-1-kontext-max: la presenza o meno di input_image determina il percorso, e il prezzo è lo stesso.

Quante immagini di riferimento si possono inviare alla volta? Una. Per fondere più immagini, scegli la modifica immagini di GPT Image 2, che supporta da 1 a 16 immagini di riferimento.

Si possono usare prompt in cinese? Sì. Il limite del prompt è di 4.000 caratteri; il cinese viene tradotto automaticamente in inglese prima della generazione.

Il formato cambia dopo la modifica? Se non specifichi aspect_ratio, mantieni le proporzioni originali con pixel arrotondati a multipli di 32; se lo specifichi, l'immagine viene ritagliata o estesa al rapporto indicato.

Le attività fallite comportano addebiti? La fatturazione si basa sul numero di immagini generate con successo; ogni richiesta restituisce 1 immagine e i crediti delle attività fallite vengono rimborsati.

Copia il prompt dell'angolo lettura qui sopra nella pagina del modello FLUX.1 Kontext Max, seleziona 16:9 e clicca Genera una volta: osserva come gestisce luce e materiali, poi decidi se integrarlo nel tuo progetto.