Black Forest LabsGuida

Come usare l’API di FLUX.2 [max]

Una guida passo passo all’API di FLUX.2 [max] con Node.js, Python e cURL: invia un job da testo a immagine, controllane lo stato o ricevi un webhook e scarica il image. L’esempio qui sotto costa $0,065.

Endpoint: 1; Da testo a immagine
Richiesta di esempio: $0,065; Da testo a immagine
Linguaggi: 3; Node.js · Python · cURL
Generazioni non riuscite: $0; rimborsate automaticamente

Ottieni una chiave API Crea con FLUX.2 [max]Documentazione API

Ottieni una chiave API

Crea un account, aggiungi crediti e crea una chiave nella Dashboard → Chiavi API. Salvala come CHEAPERGEN_API_KEY sul tuo server. Ogni richiesta la invia come token Bearer.

Come ottenere una chiave API FLUX.2 [max]

Scegli un endpoint FLUX.2 [max]

Ogni attività ha il proprio endpoint. Tutti accettano un corpo JSON e restituiscono una generazione di cui puoi controllare lo stato.

Endpoint API di FLUX.2 [max], input obbligatori e prezzi
Attività	Endpoint	Obbligatorio	Da
Da testo a immagine	bfl/flux-2-max/text-to-image	prompt	$0,0644 per immagine

Invia un job da testo a immagine

Questo programma invia il job, controlla ogni 3 secondi finché non termina e stampa l’URL image. Sostituisci il prompt e le impostazioni con i tuoi.

const API = "https://cheapergen.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Submit the job
let job = await fetch(`${API}/run/bfl/flux-2-max/text-to-image`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "Foto editoriale di un vaso in ceramica con fiori secchi su un tavolo coperto di lino, luce morbida da nord, grana da pellicola",
    "aspect_ratio": "1:1",
    "resolution": "1MP"
  }),
}).then((r) => r.json());

// 2. Poll until it finishes (or pass webhook_url and skip polling)
while (job.status === "queued" || job.status === "running") {
  await new Promise((r) => setTimeout(r, 3000));
  job = await fetch(`${API}/generations/${job.id}`, { headers }).then((r) => r.json());
}

console.log(job.status === "succeeded" ? job.output.images[0].url : job.error);

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

# 1. Submit the job
job = requests.post(f"{API}/run/bfl/flux-2-max/text-to-image", headers=headers, json={
    "prompt": "Foto editoriale di un vaso in ceramica con fiori secchi su un tavolo coperto di lino, luce morbida da nord, grana da pellicola",
    "aspect_ratio": "1:1",
    "resolution": "1MP"
}).json()

# 2. Poll until it finishes (or pass "webhook_url" and skip polling)
while job["status"] in ("queued", "running"):
    time.sleep(3)
    job = requests.get(f"{API}/generations/{job['id']}", headers=headers).json()

print(job["status"], job["output"]["images"][0]["url"] if job["status"] == "succeeded" else job["error"])

curl -X POST https://cheapergen.com/api/v1/run/bfl/flux-2-max/text-to-image \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Foto editoriale di un vaso in ceramica con fiori secchi su un tavolo coperto di lino, luce morbida da nord, grana da pellicola",
  "aspect_ratio": "1:1",
  "resolution": "1MP"
}'

Imposta i parametri rilevanti

Le impostazioni di bfl/flux-2-max/text-to-image e il loro effetto sul prezzo.

Parametri FLUX.2 [max] Da testo a immagine e relativo effetto sul prezzo
Parametro	Tipo · predefinito	Descrizione	Effetto sul prezzo
aspect_ratio	string (enum) · 1:1	Formato dell'immagine di output. 1:1 · 4:3 · 3:4 · 16:9 · 9:16 · 3:2 · 2:3 · 21:9 · 9:21	Sì
resolution	string (enum) · 1MP	Dimensione di output in megapixel (1 MP ≈ 1024×1024). FLUX.2 viene fatturato per megapixel. 1MP · 2MP · 3MP · 4MP	1 MP: $0,0644 per immagine 2 MP: $0,0889 per immagine 3 MP: $0,1091 per immagine 4 MP: $0,1263 per immagine
prompt_upsampling	boolean · false	Consenti al modello di ampliare e riscrivere il prompt prima di generare.	Nessuno
seed	integer	Usa lo stesso seed e le stesse impostazioni per riprodurre un risultato. Lascia vuoto per un valore casuale.	Nessuno

Ottieni il risultato

Un job passa da queued a running, poi a succeeded, failed o canceled. Interroga GET /api/v1/generations/{id} oppure imposta webhook_url: invieremo il risultato con POST. Scarica l’output e conservalo tu.

200 — completata

{
  "id": "gen_8c2QmX1nq0k4",
  "object": "generation",
  "model": "bfl/flux-2-max",
  "endpoint": "bfl/flux-2-max/text-to-image",
  "mode": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Foto editoriale di un vaso in ceramica con fiori secchi su un tavolo coperto di lino, luce morbida da nord, grana da pellicola",
    "aspect_ratio": "1:1",
    "resolution": "1MP"
  },
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2Q-0.png",
        "content_type": "image/png",
        "width": 2048,
        "height": 2048
      }
    ]
  },
  "error": null,
  "cost": {
    "amount_usd": 0.2255,
    "currency": "usd",
    "estimated": false,
    "official_usd": 0.264,
    "list_price_source": "official",
    "list_price_label": "Official",
    "saved_usd": 0.0385
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04Z",
  "started_at": "2026-10-15T09:21:06Z",
  "completed_at": "2026-10-15T09:22:31Z"
}

Verifica le firme dei webhook

Calcola il prezzo prima dell'avvio

L'endpoint dei preventivi è gratuito e non richiede una chiave. Restituisce il prezzo, il prezzo ufficiale e lo sconto applicato per l'input esatto che invii.

curl -X POST https://cheapergen.com/api/v1/quote/bfl/flux-2-max/text-to-image \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Foto editoriale di un vaso in ceramica con fiori secchi su un tavolo coperto di lino, luce morbida da nord, grana da pellicola","aspect_ratio":"1:1","resolution":"1MP"}'

Errori API e come risolverli
Stato	Codice	Descrizione
400	invalid_request	Manca un parametro o il suo valore è fuori intervallo: il messaggio indica quale.
401	unauthorized	Chiave API mancante, non valida o revocata.
402	insufficient_balance	Crediti insufficienti per il prezzo indicato; aggiungine altri o attiva la ricarica automatica.
429	rate_limited	Troppe richieste o generazioni in corso: attendi e riprova con backoff.
502	upstream_error	Il fornitore del modello ha avuto un errore; l'importo bloccato viene rimborsato e puoi riprovare.
503	model_unavailable	Al momento non ci sono percorsi di elaborazione disponibili: riprova più tardi o scegli un altro modello.

Documentazione API completa di FLUX.2 [max]

FAQ

Domande sull’API di FLUX.2 [max]

No. L'API usa HTTPS semplice e JSON, quindi gli esempi con Node.js (fetch) e Python (requests) in questa pagina sono programmi completi. Funziona qualsiasi linguaggio in grado di inviare una richiesta HTTP.

Sì. Aggiungi "webhook_url" al corpo della richiesta e invieremo la generazione completata con una richiesta POST, firmata nell'intestazione CheaperGen-Signature (HMAC-SHA256 del timestamp e del corpo grezzo). Puoi anche eseguire il polling con GET /api/v1/generations/{id}.

Da testo a immagine parte da $0,0644 per immagine; l'esempio di richiesta in questa pagina costa $0,065, 8% in meno rispetto a il prezzo ufficiale. Le generazioni non riuscite vengono rimborsate automaticamente.