FLUX 3 Image API: guida a 4K e riferimenti multipli

FLUX 3 Image è già disponibile attraverso un modello Replicate di proprietà di Black Forest Labs e diversi endpoint partner, con output 4K e modifica basata su un massimo di 10 immagini di riferimento. La documentazione nativa di BFL continua però a concentrarsi su FLUX 3 Video, mentre i provider dedicati alle immagini adottano schemi, limiti e sistemi di fatturazione differenti.

FLUX 3 Image API è davvero disponibile?

Sì, ma la parola “ufficiale” va usata con precisione. La prova più solida è la pagina attiva di black-forest-labs/flux-3-image su Replicate, che appartiene a Black Forest Labs. L'endpoint accetta richieste di generazione, passa alla modalità di modifica quando viene fornita un'immagine e mette a disposizione 4k come valore di risoluzione.

L'articolo di assistenza BFL su FLUX 3 descrive soltanto il modello video; la pagina Replicate di proprietà di BFL e gli endpoint partner separati confermano invece la disponibilità dell'editing di immagini.

Prima che comparisse l'endpoint, l'utente Reddit u/rerri aveva previsto un lancio incentrato sulle API:

“I wouldn't be surprised if the API-only Flux 3 Image launches first.” — u/rerri on r/StableDiffusion

Il lancio segue quella previsione, ma la disponibilità via API non significa che i pesi del modello siano open source.

Cosa significano davvero editing 4K e riferimenti multipli

FLUX 3 Image offre un'opzione di output 4k e accetta fino a 10 immagini di riferimento. Nessuno dei due parametri garantisce però che il risultato conservi alla perfezione ogni identità, dettaglio del prodotto o riga di testo di piccole dimensioni: le pagine dei provider mostrano controlli ed esempi, non valutazioni indipendenti della qualità.

Il README di Replicate relativo al modello di proprietà di BFL elenca 768sq, 1k, 1.5k, 2k e 4k. I file di riferimento possono essere JPEG, PNG, GIF o WebP, devono avere almeno 256 per 256 pixel e non possono superare i 16 megapixel. Con aspect_ratio: auto, è il primo riferimento a determinare il rapporto d'aspetto dell'editing.

Lo schema di editing di fal è simile, ma non identico. Accetta da 1 a 10 URL o data URI, impone un limite di 4 megapixel per ogni input, supporta valori da 512sq a 4k e avverte che l'elaborazione in 4K può richiedere diversi minuti. Anche l'ordine dei riferimenti ha un significato: “immagine 1” indica il primo elemento di image_urls.

Per gli editing con più riferimenti, assegna a ogni input un ruolo preciso: composizione di base, identità del soggetto, prodotto o stile. Le indicazioni dello stesso fal suggeriscono di limitarsi a una modifica per richiesta. Un prompt come “Usa l'immagine 1 come base; sostituisci soltanto la bottiglia con il prodotto dell'immagine 2; conserva angolazione della fotocamera, mani, illuminazione e sfondo” è più facile da verificare rispetto a una richiesta che modifica contemporaneamente anche abbigliamento, tipografia e ambientazione.

Un workflow pratico con API in coda

In produzione, FLUX 3 Image va trattato come un job asincrono. L'applicazione carica URL stabili per gli input, invia una richiesta circoscritta, salva l'ID restituito dal provider, controlla lo stato con un backoff progressivo e copia il risultato completato nel proprio storage.

L'esempio seguente usa l'identificativo dell'endpoint e i campi documentati da fal. È un modello d'integrazione, non la dichiarazione che la richiesta sia stata eseguita durante questa analisi.

import os
import time
import requests

ENDPOINT = "https://queue.fal.run/blackforestlabs/flux-3/edit-image"
headers = {
    "Authorization": f"Key {os.environ['FAL_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "prompt": (
        "Use image 1 as the base. Replace only its package with the product "
        "from image 2. Preserve the hands, camera angle, shadows, and background."
    ),
    "image_urls": [
        "https://cdn.example.com/base.jpg",
        "https://cdn.example.com/product.png",
    ],
    "resolution": "1k",
    "aspect_ratio": "auto",
    "output_format": "png",
    "safety_tolerance": 2,
}

submitted = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)
submitted.raise_for_status()
job = submitted.json()

status_url = job["status_url"]
response_url = job["response_url"]
while True:
    status = requests.get(status_url, headers=headers, timeout=30)
    status.raise_for_status()
    state = status.json().get("status")
    if state == "COMPLETED":
        break
    if state in {"FAILED", "CANCELLED"}:
        raise RuntimeError(status.text)
    time.sleep(2)

result = requests.get(response_url, headers=headers, timeout=30)
result.raise_for_status()
print(result.json())

La documentazione della coda fal collegata dalla pagina del modello espone anche sync_mode, ma per il 4K l'esecuzione in coda è il default più prudente: il rendering può durare più a lungo del normale timeout di una richiesta HTTP. Layer rende esplicito questo contratto asincrono: l'invio restituisce HTTP 202, un inference_id e un intervallo di polling consigliato. Layer supporta inoltre chiavi di idempotenza riutilizzabili per 24 ore, utili per evitare addebiti duplicati dopo i retry di rete.

Prima di attivare il traffico reale:

1. Rifiuta le immagini sotto i 256 pixel per lato e applica il limite di megapixel del provider selezionato.
2. Conserva l'ordine degli array e genera prompt che facciano riferimento a image 1, image 2 e così via.
3. Usa una chiave di idempotenza univoca quando il provider la supporta; in caso contrario, salva la richiesta prima di ritentare.
4. Imposta un limite al polling e mostra uno stato di attesa invece di mantenere aperta la richiesta dell'applicazione.
5. Copia i file completati in uno storage sotto il tuo controllo, perché gli URL dei risultati ospitati potrebbero non rispettare le policy di conservazione dell'applicazione.
6. Registra per ogni job ID del modello, provider, risoluzione, numero di riferimenti, costo quotato, tempo trascorso ed esito della moderazione.

Il compromesso reale tra costi e qualità

Il confronto dei costi va tenuto nei limiti dei dati disponibili: sulle pagine verificate i provider non pubblicavano una tabella completa dei prezzi per risoluzione. fal indicava un prezzo promozionale di $0.024 per immagine a 1K, destinato a salire a $0.048 dopo la promozione; specificava inoltre che il numero di riferimenti non modifica l'addebito. Su quella pagina del modello non erano riportati i prezzi esatti per 2K e 4K, quindi non è possibile ricavare il budget 4K dalla cifra relativa al formato 1K.

Meglio adottare una policy in due fasi, invece di dare per scontato che il 4K sia sempre la scelta migliore:

Una risoluzione maggiore offre più pixel, non necessariamente un editing più fedele: un risultato sbagliato a 1K diventa soltanto un errore più grande in 4K. Riserva il 4K agli editing approvati destinati alla stampa, a layout per billboard o a ritagli molto spinti.

All'avvio dell'applicazione, invia un job di test minimo ma valido oppure interroga la superficie dei prezzi del provider, registra l'addebito quotato e disabilita il 4K se il preventivo manca o supera il budget del job. La risposta iniziale di Layer può includere estimated_price_creative_units; la pagina pubblica del modello non forniva però una conversione in dollari. La pagina recuperata di Replicate documentava gli input, ma non un prezzo fisso. Sono lacune da risolvere nel pannello dell'account prima del lancio, non cifre da inventare nel codice.

Scegli l'endpoint in base alle esigenze operative

La scelta del provider deve seguire il contratto di cui ha bisogno l'applicazione. La sola proprietà del modello non rende intercambiabili gli schemi.

• Replicate: scegli la pagina di proprietà di BFL quando la provenienza è la priorità e il tuo stack utilizza già il workflow di prediction di Replicate. Qui documenta il limite di input più ampio, pari a 16 MP, e include anche il grounding opzionale sul web e sulle immagini.
• fal: scegli l'endpoint partner per l'editing quando sono più importanti controlli chiari sulle immagini, un workflow basato su coda e un prezzo 1K visibile. Il limite di 4 MP per gli input richiede di ridimensionare prima i file.
• Layer: scegli Layer se ti servono organizzazione del workspace, un contratto HTTP 202 esplicito, indicazioni per il polling e idempotenza per 24 ore. Verifica come le Creative Units vengono convertite in dollari prima di impostare un budget.

Non identificare un provider soltanto perché nel dominio o nel nome del repository compare “FLUX3”. Verifica l'ID del modello, il proprietario o l'etichetta del partner, i valori enum aggiornati, le condizioni commerciali e l'esito di una richiesta a basso costo. Il wrapper Anil-matcha/Flux-3-Dev-API, tra i risultati con il ranking più alto, indicava ancora le proprie route per le immagini come “coming soon” al momento della verifica, mentre le route di Replicate di proprietà di BFL e il percorso partner di fal erano attive.

Checklist prima del rilascio in produzione

FLUX 3 Image è adatto ai test controllati via API, inclusi output 4K e fino a 10 riferimenti. Va portato in produzione solo dopo aver verificato lo stesso set rappresentativo di editing sull'endpoint scelto, prima a 1K e poi alla risoluzione finale.

La raccomandazione pratica è partire dall'editing a 1K, registrare dati su preventivi e latenza e abilitare 2K o 4K soltanto per i finali approvati. In questo modo le capacità più interessanti e documentate del nuovo modello restano disponibili, senza fare supposizioni non verificate sulla qualità o sui costi dell'alta risoluzione.

Articoli correlati

• Panoramica del prodotto FLUX 3
• Confronto tra le API per la generazione di immagini più economiche