FLUX.2 Klein Tutorial: crea un'app di generazione e modifica immagini con Gradio

Passo 1: Configurazione dell'ambiente

Prima di costruire la nostra app di generazione e modifica immagini, dobbiamo impostare un ambiente pulito con l'ultima libreria Diffusers. Per questo tutorial, eseguiremo tutto su un'istanza Google Colab con GPU A100 per una generazione più veloce. Detto ciò, la stessa configurazione funziona anche su GPU più modeste, come una T4, con prestazioni leggermente inferiori.

Iniziamo disinstallando eventuali versioni esistenti di Diffusers per evitare conflitti di versione, quindi installiamo l'ultima versione di sviluppo direttamente da GitHub. Installiamo anche le librerie di supporto necessarie per il caricamento del modello, la gestione dei checkpoint e l'accelerazione.

!pip -q uninstall -y diffusers
!pip -q install -U git+https://github.com/huggingface/diffusers.git
!pip -q install -U accelerate safetensors transformers huggingface_hub

Una volta completata l'installazione, controlliamo la versione di Diffusers installata e confermiamo che la classe Flux2KleinPipeline possa essere importata correttamente.

import diffusers
print("diffusers:", diffusers.__version__)
from diffusers import Flux2KleinPipeline
print("Flux2KleinPipeline import OK")

Questo conferma che il nostro ambiente è configurato correttamente. Nel prossimo passo, caricheremo il modello FLUX.2 Klein sulla GPU e lo prepareremo sia per la generazione locale di immagini sia per i workflow di editing basati su API.

Passo 2: Caricare FLUX.2 Klein 4B 

Prima di caricare il modello, ti serve una chiave API di Black Forest Labs. Per iniziare, accedi al tuo account Black Forest Labs e aggiungi crediti nella scheda Credits. La ricarica minima è di circa dieci dollari, che corrispondono a circa mille crediti. Una volta aggiunti i crediti, clicca su Create Key, assegnale un nome descrittivo e conservala in modo sicuro.

Con la tua chiave API pronta, il passo successivo è caricare il modello FLUX.2 Klein 4B e prepararlo per due modalità d'uso diverse: generazione di immagini in locale ed editing di immagini via API. 

import os, time, base64, io, requests
import gradio as gr
import torch
import nest_asyncio
from PIL import Image
from diffusers import Flux2KleinPipeline
from google.colab import userdata
nest_asyncio.apply()
# =============================
# LOAD via API
# =============================
MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"
BFL_API_KEY = userdata.get("BFL_API_KEY")
BFL_CREATE_URL = "https://api.bfl.ai/v1/flux-2-klein-4b"
print(f"Loading model to GPU: {torch.cuda.get_device_name(0)}")
# =============================
# LOAD via LOCAL HF PIPELINE
# =============================
dtype = torch.float16 
pipe = Flux2KleinPipeline.from_pretrained(MODEL_ID, torch_dtype=dtype).to("cuda")

Iniziamo configurando la chiave API come secret di Colab, così non appare mai nel codice del notebook. Definiamo anche l'ID del modello e l'endpoint di editing Klein che chiameremo più avanti. 

Successivamente applichiamo nest_asyncio prima di lanciare la UI di Gradio per evitare conflitti con il loop degli eventi.

Infine, carichiamo la pipeline locale FLUX.2 Klein per la generazione dell'immagine base. Usiamo Flux2KleinPipeline con float16 per un'ampia compatibilità GPU (A100 e T4 funzionano bene), quindi spostiamo la pipeline su CUDA per un'inferenza rapida. Questa pipeline locale viene usata solo per generare l'immagine iniziale, mentre le modifiche sono gestite tramite API.

Nota: a questo punto potresti chiederti perché carichiamo il modello in locale e configuriamo anche l'accesso via API. Il motivo è la separazione delle capacità:

• La pipeline locale Hugging Face è ideale per la generazione text-to-image iterativa e il pieno controllo delle impostazioni di inferenza.
• L'API di Black Forest Labs espone funzionalità avanzate di fotoritocco per FLUX.2 Klein non attualmente disponibili nell'implementazione open-weight, come modifiche basate su prompt con più immagini di riferimento.

Combinando entrambi gli approcci otteniamo il meglio di entrambi i mondi: velocità di generazione locale e supporto all'editing.

Passo 3: Funzioni di supporto

Prima di collegare il tutto all'interfaccia Gradio, ci serve un piccolo set di funzioni di supporto. Poiché la nostra app genera immagini in locale ma le modifica tramite API, ci serve un modo per codificare le immagini in base64 per le richieste API, un modo per scaricare le immagini modificate restituite come URL e una funzione di generazione locale che produca l'immagine di base iniziale.

def pil_to_b64_png(img: Image.Image) -> str:
    buf = io.BytesIO()
    img.convert("RGB").save(buf, format="PNG")
    return base64.b64encode(buf.getvalue()).decode()
def url_to_pil(url: str) -> Image.Image:
    r = requests.get(url, timeout=60)
    r.raise_for_status()
    return Image.open(io.BytesIO(r.content)).convert("RGB")
def local_generate(prompt: str):
    if not prompt.strip():
        raise gr.Error("Prompt is empty.")
    out = pipe(
        prompt=prompt.strip(),
        width=1024,
        height=1024,
        num_inference_steps=4,
        guidance_scale=1.0,
        output_type="pil",
    )
    return out.images[0].convert("RGB")

Il codice sopra definisce tre funzioni chiave di supporto:

• La funzione pil_to_b64_png() converte un'immagine PIL in una stringa PNG codificata in base64. Questo è necessario perché l'API di editing di FLUX.2 accetta l'immagine di base e le immagini di riferimento come URL o stringhe base64. 
• La funzione url_to_pil() gestisce la direzione opposta. L'API di editing restituisce un URL firmato per l'output generato, quindi scarichiamo quell'URL con requests, validiamo la risposta e convertiamo i byte scaricati di nuovo in un'immagine PIL. Questo consente di visualizzare direttamente il risultato modificato nella nostra interfaccia Gradio e salvarlo in cronologia.
• Infine, local_generate() è il nostro punto d'ingresso locale text-to-image. Valida che il prompt non sia vuoto, quindi chiama la Flux2KleinPipeline locale con impostazioni fisse come risoluzione, numero di step e guidance scale. L'output viene restituito come immagine PIL RGB pulita, che diventa l'immagine di base per le modifiche successive.

Sentiti libero di sperimentare con le impostazioni della pipeline Flux, come risoluzione, step di diffusione e guidance scale, per esplorare diversi compromessi qualità-velocità e capire meglio come ogni parametro influenza l'immagine finale. 

La documentazione per il fotoritocco di Flux 2 è un buon punto di partenza per approfondire queste impostazioni.

Nel prossimo passo useremo queste utility per implementare l'editing di immagini via API con FLUX.2 Klein.

Passo 4: Editing tramite API BFL

Questo passo è la differenza principale tra un workflow puramente Hugging Face e l'approccio ibrido usato in questo tutorial. Invece di tentare di eseguire l'editing in locale, deleghiamo le modifiche all'API, che gestisce in modo affidabile gli edit basati su prompt e il conditioning multi-referenza opzionale.

A grandi linee, l'API di editing FLUX.2 Klein si aspetta un prompt testuale che descriva la modifica, un'immagine base da modificare e immagini di riferimento opzionali fornite come input aggiuntivi. L'API è asincrona: inviamo una richiesta e poi interroghiamo un URL restituito finché l'immagine modificata non è pronta.

POLL_INTERVAL_S = 1.0
POLL_TIMEOUT_S = 120
def bfl_edit(edit_prompt, base_img, ref_imgs=None):
    if not BFL_API_KEY:
        raise gr.Error("Missing BFL_API_KEY in Colab Secrets.") 
    payload = {
        "prompt": edit_prompt.strip(),
        "input_image": pil_to_b64_png(base_img),
        "output_format": "png",
    }
    if ref_imgs:
        for i, ref in enumerate(ref_imgs[:3], start=2):
            payload[f"input_image_{i}"] = pil_to_b64_png(ref)
    create = requests.post(
        BFL_CREATE_URL,
        headers={"x-key": BFL_API_KEY, "accept": "application/json"},
        json=payload,
        timeout=60,
    )
    create.raise_for_status()
    job = create.json()
    polling_url = job.get("polling_url")
    if not polling_url:
        raise gr.Error(f"API Error: {job}")
    t0 = time.time()
    while True:
        if time.time() - t0 > POLL_TIMEOUT_S:
            raise gr.Error("BFL API polling timed out.")  
        time.sleep(POLL_INTERVAL_S)
        res = requests.get(polling_url, headers={"x-key": BFL_API_KEY})
        res.raise_for_status()
        j = res.json()
        if j["status"] == "Ready":
            return url_to_pil(j["result"]["sample"])
        if j["status"] in ("Error", "Failed"):
            raise gr.Error(f"Generation Failed: {j}")

La funzione bfl_edit() fa tre cose importanti:

• Riceve tre input: il prompt di editing, l'immagine base da modificare e un elenco opzionale di immagini di riferimento. 
• Costruiamo un payload JSON con il prompt di modifica e l'immagine base codificata come PNG base64. Se vengono fornite immagini di riferimento, le alleghiamo usando il formato indicizzato dell'API. Questo ci consente di fornire fino a tre immagini di riferimento oltre all'immagine base, sufficiente per molti workflow pratici come trasferimento di palette, ancoraggio di stile o grounding di oggetti.
• Quindi inviamo la richiesta all'endpoint API e analizziamo la risposta. L'API restituisce una polling_url che dobbiamo interrogare ripetutamente finché il job non termina. Implementiamo ciò con un semplice loop di polling con due protezioni: un intervallo di polling per evitare richieste eccessive e un timeout per impedire al notebook di attendere indefinitamente.

Quando lo stato diventa Ready, la risposta dell'API contiene un URL firmato per l'immagine di output. Scarichiamo quell'immagine usando la nostra funzione di supporto url_to_pil() e la restituiamo come immagine PIL.

Nel passo successivo implementeremo la cronologia di sessione, così l'utente può rivedere qualsiasi output generato o modificato.

Passo 5: Aggiungere la cronologia 

A questo punto, l'ultimo tassello che ci serve prima di costruire la UI è un leggero livello di memoria di sessione, così gli utenti possono rivedere gli output precedenti. Implementiamo la cronologia usando due oggetti di stato Gradio:

• base_img_state memorizza l'immagine su cui si sta lavorando (quella a cui si applicheranno le modifiche future).
• history_state memorizza ogni versione generata o modificata come elenco di dizionari, ciascuno contenente un'immagine e un'etichetta breve.

def update_history(history):
    choices = [f"{i}: {h['label']}" for i, h in enumerate(history or [])]
    return gr.update(choices=choices, value=choices[-1] if choices else None)
def on_generate(prompt, history):
    img = local_generate(prompt)
    new_history = list(history or [])
    new_history.append({"img": img, "label": "Generated Base"})
    return img, img, new_history, update_history(new_history), "Base image generated."
def on_edit(edit_prompt, ref2, ref3, ref4, base_img, history):
    if base_img is None:
        raise gr.Error("Please generate a base image first.")
    refs = [r.convert("RGB") for r in (ref2, ref3, ref4) if r is not None]
    out = bfl_edit(edit_prompt, base_img, refs)
    new_history = list(history or [])
    new_history.append({"img": out, "label": f"Edit: {edit_prompt[:20]}..."})
    return out, out, new_history, update_history(new_history), "Edit successful."
def on_load(choice, history):
    if not history or not choice:
        return None, None, "No history to load."
    idx = int(choice.split(":")[0])
    img = history[idx]["img"]
    return img, img, f"Loaded entry #{idx}."
def on_clear():
    return None, None, [], gr.update(choices=[], value=None), "Cleared everything."

Le funzioni sopra costituiscono la logica centrale per mantenere la cronologia delle immagini nella nostra demo:

• La funzione update_history() formatta la cronologia di sessione in un menu a discesa. Ogni voce è etichettata con il proprio indice e una breve descrizione, e il menu seleziona automaticamente l'elemento più recente per impostazione predefinita. Questo mantiene la UI sincronizzata senza richiedere logiche di refresh manuali.
• La callback on_generate() esegue local_generate() per creare l'immagine base iniziale. Poi aggiunge il risultato alla cronologia come {"img": img, "label": "Generated Base"}. La funzione restituisce sia l'immagine sia lo stato della cronologia aggiornato, insieme all'aggiornamento del menu a discesa così la nuova voce diventa visibile subito.
• La callback on_edit() è simile, ma chiama bfl_edit(). Prende l'immagine su cui si sta lavorando e alcune immagini di riferimento opzionali, applica la modifica via API e aggiunge l'output alla cronologia. Restituisce anche l'output modificato come nuovo base_img_state, il che significa che le modifiche future si applicano all'immagine più recente, a meno che l'utente non carichi esplicitamente una versione precedente.
• La callback on_load() analizza la voce selezionata nel menu a discesa, recupera l'immagine corrispondente da history_state e rende di nuovo quell'immagine l'immagine attiva su cui lavorare. Questo consente agli utenti di ramificare le modifiche da qualsiasi checkpoint precedente.
• Infine, la funzione on_clear() azzera tutto. Cancella l'output, azzera lo stato dell'immagine base, reimposta l'elenco della cronologia e svuota le opzioni del menu a discesa.

Colleghiamo ora queste funzioni a un'interfaccia Gradio con due caselle di testo, caricamenti di riferimento opzionali e una cronologia di lavoro.

Passo 6: UI Gradio

Questo passo collega la nostra logica di generazione, editing e cronologia a una semplice interfaccia Gradio. L'interfaccia è costruita con gr.Blocks, che ci dà un controllo granulare sul layout. 

with gr.Blocks() as demo:
    gr.Markdown("## FLUX.2 Klein: Generate & Edit Images")
    with gr.Row():
        with gr.Column(scale=1):
            gen_prompt = gr.Textbox(label="1. Generate Base Image", placeholder="A young boy riding a scooter...")
            gen_btn = gr.Button("Generate Base Image", variant="primary")
            edit_prompt = gr.Textbox(label="2. Describe Edits", placeholder="Add the red hat and yellow glasses from the references...")
            with gr.Accordion("Reference Images (Optional)", open=False):
                r2 = gr.Image(label="Ref 1", type="pil")
                r3 = gr.Image(label="Ref 2", type="pil")
                r4 = gr.Image(label="Ref 3", type="pil")
            edit_btn = gr.Button("Apply Edit", variant="secondary") 
            history_dd = gr.Dropdown(label="Session History", choices=[])
            with gr.Row():
                load_btn = gr.Button("Load Selected")
                clear_btn = gr.Button("Clear All")
            status = gr.Textbox(label="Status", interactive=False)
        with gr.Column(scale=1):
            output_view = gr.Image(label="Current Image", type="pil")
    base_img_state = gr.State(None)
    history_state = gr.State([])
    gen_btn.click(
        on_generate, 
        [gen_prompt, history_state], 
        [output_view, base_img_state, history_state, history_dd, status]
    ) 
    edit_btn.click(
        on_edit, 
        [edit_prompt, r2, r3, r4, base_img_state, history_state], 
        [output_view, base_img_state, history_state, history_dd, status]
    ) 
    load_btn.click(
        on_load, 
        [history_dd, history_state], 
        [output_view, base_img_state, status]
    )
    clear_btn.click(
        on_clear, 
        None, 
        [output_view, base_img_state, history_state, history_dd, status]
    )
demo.launch(share=True, inline=True, debug = True)

Organizziamo la UI in due colonne: a sinistra gli input e le azioni, a destra l'immagine corrente. Ecco come costruiamo l'app Gradio:

• La prima casella di testo raccoglie il prompt di generazione e il pulsante Generate Base Image attiva la funzione on_generate(). Questa callback esegue la generazione locale, salva l'output in cronologia e aggiorna sia l'immagine mostrata sia l'immagine di lavoro corrente memorizzata in base_img_state.
• La seconda casella di testo raccoglie un prompt di istruzioni per l'editing. Quando l'utente clicca Apply Edit, chiamiamo la funzione on_edit(), che usa l'immagine di lavoro corrente come immagine base e restituisce l'output modificato. L'output modificato viene anche aggiunto alla cronologia e diventa la nuova immagine di lavoro per le modifiche successive.
• Per rendere il workflow consapevole della sessione, includiamo anche un menu a discesa Session History in cui ogni voce corrisponde a una versione salvata dell'immagine. Il pulsante Load Selected attiva on_load(), che ripristina l'immagine scelta dalla cronologia e la imposta di nuovo come immagine di lavoro. 
• Infine, il pulsante Clear All azzera tutto tramite la funzione on_clear(), inclusi la visualizzazione dell'output, lo stato dell'immagine base e la cronologia memorizzata.

I due oggetti State di Gradio seguenti mantengono tutto coerente:

• base_img_state garantisce che ogni modifica si applichi all'immagine corretta.
• history_state memorizza l'intera timeline degli output per replay e ramificazioni.

Infine, demo.launch() avvia l'app in Colab, fornisce un link condivisibile, la rende inline e abilita i log di debug per aiutare a diagnosticare eventuali problemi durante lo sviluppo.

Esempi e osservazioni su FLUX.2 Klein

Per capire come si comporta FLUX.2 Klein in pratica, ho eseguito una serie di piccoli esperimenti usando l'app finale di Generazione e Modifica. Ho testato tre principali modalità di interazione: generazione dell'immagine base, editing solo con prompt e editing guidato da riferimenti usando una o più immagini. Ho anche verificato il workflow di cronologia di sessione per confermare di poter ripristinare qualsiasi output precedente e continuare a modificare da quel punto.

Generazione di immagini

Sono partito con un semplice prompt di generazione per creare un'immagine di base pulita. Il modello ha prodotto un soggetto coerente con illuminazione costante, dettagli del viso nitidi e un layout della scena stabile. L'immagine base risultante era valida e utile per modifiche successive, senza dover rigenerare.

Editing con un'unica immagine di riferimento

Successivamente, ho testato una singola immagine di riferimento come sorgente di colore e ho usato un'istruzione di editing come “Cambia il colore del vestito con quello dell'immagine di riferimento.”. La modifica ha trasferito con successo il colore desiderato preservando gran parte della struttura originale della scena.

Per quanto ho osservato, le modifiche con singolo riferimento funzionano meglio quando il prompt è stretto e vincolato. Il trasferimento di colore e il ricolorimento del guardaroba sono particolarmente affidabili perché non richiedono grandi cambiamenti di geometria. Quando l'istruzione di modifica rimane concentrata su un solo attributo, l'identità del soggetto e i dettagli dello sfondo restano stabili.

Editing con un singolo prompt

Poi ho provato l'editing solo con prompt con un cambiamento semantico, ad esempio “Sostituisci lo sfondo con una spiaggia.” Il modello ha gestito bene la sostituzione dello sfondo, mantenendo il soggetto grosso modo coerente. 

Quando cambia lo sfondo, il modello spesso regola la temperatura colore e l'intensità delle ombre per mantenere il risultato fotorealistico. Di solito è un vantaggio, ma significa che l'immagine modificata può sembrare uno scatto diverso piuttosto che un semplice ritaglio e incolla.

Guida alla posa

Ho testato una modifica basata sulla posa usando un'immagine di riferimento che implicava il posizionamento del corpo, combinata con un prompt come “Abbina una posa da un'immagine di riferimento.” L'immagine risultante ha cambiato la posa del soggetto mantenendo un'identità e uno styling simili.

Ecco l'immagine di riferimento che ho usato per la guida alla posa:

Le modifiche di posa sono fattibili, ma più sensibili rispetto a quelle di colore. Qualsiasi cambio di posa può innescare cambiamenti secondari come la caduta del tessuto, la posizione degli arti e l'inquadratura della fotocamera. Mi sono serviti un paio di tentativi per ottenere questa posa corretta, e c'erano ancora difficoltà con la posizione delle gambe.

Editing con più immagini di riferimento

Infine, ho testato modifiche multi-referenza usando diversi input, come un riferimento di palette colori e un prompt che afferma esplicitamente “Cambia solo i colori dello sfondo usando la palette delle immagini di riferimento. Non sostituire lo sfondo con le immagini di riferimento.” 

Con mia sorpresa, l'editin

g multi-referenza è più efficace quando ogni immagine di riferimento ha un ruolo chiaro. 

Le palette funzionano bene quando il prompt specifica esplicitamente solo la palette e evita di istruire il modello a usare il contenuto del riferimento come sostituzione. 

Quando i riferimenti sono ambigui, il modello può prendere in prestito texture o indizi di layout invece del solo colore.  Nel mio test, ho notato alcuni piccoli artefatti in cui elementi simili alle immagini di riferimento trapelavano sottilmente nella scena, ma il risultato complessivo appariva comunque valido e visivamente coerente.

Un vantaggio pratico di questa demo è che ogni immagine generata e modificata viene conservata nella cronologia di sessione. Puoi caricare qualsiasi voce precedente e continuare a modificare esattamente da quel checkpoint. Questo rende la sperimentazione molto più veloce. Puoi ramificare le modifiche da una versione precedente, confrontare più direzioni di editing ed evitare di perdere un buon risultato intermedio. 

Conclusione

In questo tutorial abbiamo costruito un workflow completo di generazione e fotoritocco usando FLUX.2 Klein 4B. Combinando la generazione text-to-image in locale tramite Diffusers con l'API di editing hosted di Black Forest Labs, siamo riusciti a creare un editor di immagini interattivo.

La bassa latenza di FLUX.2 Klein, le capacità unificate di generazione ed editing e il supporto multi-referenza lo rendono particolarmente adatto a questo tipo di workflow interattivo. Da qui, puoi estendere l'app con editing in batch, controlli dei parametri, persistenza tra sessioni o persino un agente guidato da LLM che propone automaticamente le modifiche.