FLUX.2 Klein-tutorial: een Generate-and-Edit-afbeeldingsapp bouwen met Gradio

Stap 1: Omgevingssetup

Voordat we onze app voor beeldgeneratie en -bewerking bouwen, richten we een schone omgeving in met de nieuwste Diffusers-bibliotheek. Voor deze tutorial draaien we alles op een Google Colab-instantie met een A100-GPU voor snellere beeldgeneratie. Dat gezegd hebbende, dezelfde setup werkt ook op bescheidener GPU’s, zoals een T4, met iets lagere prestaties.

We beginnen met het deïnstalleren van eventuele bestaande versies van Diffusers om versieconflicten te voorkomen, en installeren vervolgens de nieuwste ontwikkelversie rechtstreeks vanaf GitHub. We installeren ook ondersteunende bibliotheken die nodig zijn voor modelladen, checkpointafhandeling en acceleratie.

!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

Zodra de installatie voltooid is, controleren we de geïnstalleerde Diffusers-versie en bevestigen we dat de klasse Flux2KleinPipeline succesvol kan worden geïmporteerd.

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

Dit bevestigt dat onze omgeving correct is geconfigureerd. In de volgende stap laden we het FLUX.2 Klein-model op de GPU en bereiden we het voor op zowel lokale beeldgeneratie als API-gebaseerde bewerkingsworkflows.

Stap 2: FLUX.2 Klein 4B laden 

Voordat je het model laadt, heb je een API-sleutel van Black Forest Labs nodig. Log in op je Black Forest Labs-account en voeg tegoed toe onder het tabblad Credits. De minimale opwaardering is ongeveer tien dollar, goed voor circa duizend credits. Zodra de credits zijn toegevoegd, klik je op Create Key, geef je deze een duidelijke naam en bewaar je hem veilig.

Met je API-sleutel gereed is de volgende stap het laden van het FLUX.2 Klein 4B-model en het voorbereiden voor twee gebruiksmodi: lokale beeldgeneratie en API-gebaseerde beeldbewerking. 

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")

We configureren de API-sleutel als een Colab-geheim, zodat deze nooit in de notebookcode verschijnt. We definiëren ook de model-ID en het Klein-bewerkingsendpoint dat we later aanroepen. 

Vervolgens passen we nest_asyncio toe voordat we de Gradio-UI starten om conflicten met de eventloop te voorkomen.

Laad ten slotte de lokale FLUX.2 Klein-pijplijn voor het genereren van de basisafbeelding. We gebruiken Flux2KleinPipeline met float16 voor brede GPU-compatibiliteit (A100 en T4 werken allebei goed) en verplaatsen de pijplijn daarna naar CUDA voor snelle inferentie. Deze lokale pijplijn wordt alleen gebruikt voor het genereren van de initiële afbeelding; bewerkingen worden via de API afgehandeld.

Opmerking: op dit punt vraag je je misschien af waarom we het model lokaal laden én API-toegang configureren. De reden is scheiding van mogelijkheden:

• De lokale Hugging Face-pijplijn is ideaal voor iteratieve text-to-image-generatie en volledige controle over inferentie-instellingen.
• De Black Forest Labs-API biedt geavanceerde bewerkingsfuncties voor FLUX.2 Klein die momenteel niet beschikbaar zijn in de open-weights-implementatie, zoals promptgebaseerde beeldbewerkingen met meerdere referentieafbeeldingen.

Door beide benaderingen te combineren, krijg je het beste van twee werelden: lokale generatiesnelheid en bewerkingsondersteuning.

Stap 3: Helperfuncties

Voordat we alles in de Gradio-interface koppelen, hebben we een kleine set helperfuncties nodig. Omdat onze app lokaal afbeeldingen genereert maar ze via de API bewerkt, hebben we een manier nodig om afbeeldingen te encoderen naar base64 voor API-verzoeken, een manier om bewerkte afbeeldingen (geretourneerd als URL’s) te downloaden, en een lokale generatiefunctie die de initiële basisafbeelding maakt.

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")

De bovenstaande code definieert drie belangrijke helperfuncties:

• De functie pil_to_b64_png() zet een PIL-afbeelding om naar een base64-gecodeerde PNG-string. Dit is nodig omdat de FLUX.2-bewerkings-API de basisafbeelding en referentieafbeeldingen accepteert als URL of als base64-string. 
• De functie url_to_pil() doet het omgekeerde. De bewerkings-API retourneert een ondertekende URL voor de gegenereerde output; we halen die URL op met requests, valideren de respons en zetten de gedownloade bytes terug om naar een PIL-afbeelding. Zo kan het bewerkte resultaat direct in onze Gradio-interface worden weergegeven en in de geschiedenis worden opgeslagen.
• Tot slot is local_generate() ons lokale text-to-image-startpunt. De functie controleert of de prompt niet leeg is en roept vervolgens de lokale Flux2KleinPipeline aan met vaste instellingen zoals resolutie, aantal stappen en guidance scale. De output wordt teruggegeven als een schone RGB-PIL-afbeelding, die de basis vormt voor latere bewerkingen.

Experimenteer gerust met de FLUX-pijplijninstellingen, zoals beeldresolutie, diffusiestappen en guidance scale, om verschillende kwaliteit-snelheid-afwegingen te verkennen en beter te begrijpen hoe elke parameter het eindresultaat beïnvloedt. 

De documentatie over Flux 2-beeldbewerking is een goede plek om meer over deze instellingen te leren.

In de volgende stap gebruiken we deze hulpmiddelen om API-gebaseerde beeldbewerking met FLUX.2 Klein te implementeren.

Stap 4: Bewerken via de BFL-API

Deze stap is het belangrijkste verschil tussen een puur Hugging Face-workflow en de hybride aanpak in deze tutorial. In plaats van bewerken lokaal te proberen draaien, delegeren we bewerkingen aan de API, die promptgebaseerde edits en optionele multi-referentieconditionering betrouwbaar afhandelt.

Op hoofdlijnen verwacht de FLUX.2 Klein-bewerkings-API een tekstprompt die de bewerking beschrijft, een basisafbeelding om te wijzigen en optionele referentieafbeeldingen als aanvullende inputs. De API draait asynchroon: we dienen een verzoek in en pollen vervolgens een teruggegeven URL totdat de bewerkte afbeelding klaar is.

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}")

De functie bfl_edit() doet drie belangrijke dingen:

• Ze neemt drie inputs: de bewerkingsprompt, de basisafbeelding die we willen wijzigen en een optionele lijst met referentieafbeeldingen. 
• We bouwen een JSON-payload met de bewerkingsprompt en de basisafbeelding, gecodeerd als base64-PNG. Als er referentieafbeeldingen zijn, voegen we die toe via het geïndexeerde formaat van de API. Zo kunnen we maximaal drie referentieafbeeldingen toevoegen naast de basisafbeelding, voldoende voor veel praktische workflows zoals kleurpaletoverdracht, stijlankering of objectverankering.
• Vervolgens dienen we het verzoek in bij het API-endpoint en parseren we de respons. De API retourneert een polling_url die we herhaaldelijk moeten bevragen totdat de taak is voltooid. We implementeren dit met een eenvoudige pollingloop met twee vangrails: een poll-interval om overmatige verzoeken te vermijden en een timeout om te voorkomen dat de notebook oneindig blijft wachten.

Zodra de status Ready wordt, bevat de API-respons een ondertekende URL naar de outputafbeelding. We downloaden die afbeelding met onze eerdere helper url_to_pil() en geven haar terug als een PIL-afbeelding.

In de volgende stap implementeren we sessiegeschiedenis zodat gebruikers elk gegenereerd of bewerkt resultaat kunnen herbezoeken.

Stap 5: Geschiedenis toevoegen 

Op dit punt hebben we nog één onderdeel nodig voordat we de UI bouwen: een lichte sessiegeheugenlaag zodat gebruikers eerdere resultaten kunnen herbezoeken. We implementeren geschiedenis met twee Gradio-stateobjecten:

• base_img_state slaat de huidige werkafbeelding op (de afbeelding waarop toekomstige bewerkingen worden toegepast).
• history_state bewaart elke gegenereerde of bewerkte versie als een lijst van dictionaries, elk met een afbeelding en een kort label.

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."

De bovenstaande functies vormen de kernlogica voor het bijhouden van afbeeldingsgeschiedenis in onze demo:

• De functie update_history() formatteert de sessiegeschiedenis in een dropdown. Elk item krijgt zijn index en een korte beschrijving, en de dropdown selecteert standaard automatisch het nieuwste item. Zo blijft de UI in sync zonder handmatige verversing.
• De callback on_generate() draait local_generate() om de initiële basisafbeelding te maken. Vervolgens wordt het resultaat aan de geschiedenis toegevoegd als {"img": img, "label": "Generated Base"}. De functie retourneert zowel de afbeelding als de bijgewerkte historystate, plus een dropdown-update zodat de nieuwe entry meteen zichtbaar is.
• De callback on_edit() is vergelijkbaar, maar roept bfl_edit() aan. Ze neemt de huidige werkafbeelding en optionele referentieafbeeldingen, past de bewerking toe via de API en voegt de output toe aan de geschiedenis. De bewerkte output wordt ook de nieuwe base_img_state, wat betekent dat toekomstige edits op de meest recente afbeelding worden toegepast, tenzij de gebruiker expliciet een oudere versie laadt.
• De callback on_load() parseert het geselecteerde dropdown-item, haalt de bijbehorende afbeelding uit history_state en maakt die afbeelding weer actief als werkafbeelding. Zo kunnen gebruikers hun bewerkingen vanaf elk eerder checkpoint vertakken.
• Tot slot reset on_clear() alles. De output wordt geleegd, de basisafbeeldingstate wordt gewist, de geschiedenislijst wordt gereset en de dropdownkeuzes worden leeggemaakt.

Laten we deze functies in een Gradio-interface verwerken met twee tekstvakken, optionele referentieuploads en een geschiedenisworkflow.

Stap 6: Gradio-UI

Deze stap koppelt onze generatie-, bewerkings- en geschiedenisl ogica aan een eenvoudige Gradio-interface. De interface is gebouwd met gr.Blocks, wat fijne controle over de layout geeft. 

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)

We organiseren de UI in twee kolommen: links staan invoer en acties, rechts wordt de huidige afbeelding getoond. Zo bouwen we de Gradio-app:

• Het eerste tekstvak verzamelt de generatieprompt en de knop Generate Base Image triggert de functie on_generate(). Deze callback draait de lokale generatie, slaat de output op in de geschiedenis en werkt zowel de weergegeven afbeelding als de huidige werkafbeelding in base_img_state bij.
• Het tweede tekstvak verzamelt een instructieprompt voor bewerking. Wanneer de gebruiker op Apply Edit klikt, roepen we on_edit() aan, die de huidige werkafbeelding als basis gebruikt en de bewerkte output teruggeeft. De bewerkte output wordt ook aan de geschiedenis toegevoegd en wordt de nieuwe werkafbeelding voor volgende edits.
• Om de workflow sessiebewust te maken, voegen we ook een dropdown Session History toe, waarbij elk item overeenkomt met een opgeslagen versie van de afbeelding. De knop Load Selected triggert on_load(), die de gekozen geschiedenisafbeelding herstelt en weer instelt als huidige werkafbeelding. 
• Tot slot reset de knop Clear All alles via de functie on_clear(), inclusief de outputweergave, de basisafbeeldingstate en de opgeslagen geschiedenis.

De twee volgende Gradio-stateobjecten houden alles consistent:

• base_img_state zorgt ervoor dat elke bewerking op de juiste afbeelding wordt toegepast.
• history_state slaat de volledige tijdlijn van outputs op voor terugspelen en vertakken.

Tot slot start demo.launch() de app in Colab, biedt een deelbare link, rendert inline en schakelt debuglogs in om problemen tijdens de ontwikkeling te diagnosticeren.

FLUX.2 Klein: voorbeelden en observaties

Om te begrijpen hoe FLUX.2 Klein zich in de praktijk gedraagt, heb ik een set kleine experimenten uitgevoerd met de uiteindelijke Generate-and-Edit-app. Ik testte drie hoofdinteractiepatronen: basisbeeldgeneratie, bewerking op alleen prompt en referentiegestuurde bewerking met één of meer afbeeldingen. Ik valideerde ook de sessiegeschiedenis-workflow om te bevestigen dat ik elk eerder resultaat kan herstellen en vanaf dat punt kan doorgaan met bewerken.

Beeldgeneratie

Ik begon met een eenvoudige generatieprompt om een schone basisafbeelding te maken. Het model produceerde een coherent onderwerp met consistente belichting, scherpe gelaatsdetails en een stabiele scènelayout. De outputbasis zag er sterk uit en bruikbaar voor latere aanpassingen in plaats van een volledige regeneratie.

Beeldbewerking met één referentieafbeelding

Vervolgens testte ik een enkele referentieafbeelding als kleurbron en gebruikte ik een bewerkinstructie zoals “Verander de kleur van de jurk naar de kleur van de referentieafbeelding.” De bewerking droeg de bedoelde kleur succesvol over terwijl de meeste oorspronkelijke scène-structuur behouden bleef.

Naar mijn observatie werken bewerkingen met één referentie het best wanneer de prompt smal en begrensd is. Kleuroverdracht en het herkleuren van kleding zijn vooral betrouwbaar omdat ze geen grote geometrieveranderingen vereisen. Als de bewerkinstructie zich op één attribuut richt, blijven onderwerpidentiteit en achtergronddetails stabiel.

Beeldbewerking met alleen een prompt

Daarna probeerde ik prompt-only bewerking met een semantische wijziging, zoals “Vervang de achtergrond door een strand.” Het model verwerkte de achtergrondvervanging netjes, terwijl het onderwerp ongeveer consistent bleef. 

Wanneer de achtergrond verandert, past het model vaak de kleurtemperatuur en schaduwintensiteit aan om het resultaat fotorealistisch te houden. Dit is meestal een pluspunt, maar het betekent dat de bewerkte afbeelding kan ogen als een andere fotoshoot in plaats van een simpele knip-en-plak.

Pose-geleiding

Ik testte een posegebaseerde bewerking met een referentieafbeelding die de lichaamshouding impliceert, gecombineerd met een prompt als “Match een pose uit een referentieafbeelding.” De resulterende afbeelding verschoof de pose van het onderwerp met behoud van een vergelijkbare identiteit en styling.

Hier is de referentieafbeelding die ik gebruikte voor pose-geleiding:

Posebewerkingen zijn haalbaar, maar gevoeliger dan kleurbewerkingen. Elke posewijziging kan secundaire veranderingen veroorzaken, zoals stofval, stand van ledematen en kadrering. Het kostte me een paar pogingen om deze pose goed te krijgen en de beenplaatsing bleef lastig.

Beeldbewerking met meerdere referentieafbeeldingen

Tot slot testte ik multi-referentiebewerkingen met meerdere inputs, zoals een kleurenpaletreferentie en een bewerkinstructie die expliciet stelt: “Verander alleen achtergrondkleuren met het palet uit de referentieafbeeldingen. Vervang de achtergrond niet door de referentieafbeeldingen.” 

Tot mijn verbazing is multi-referentie bewerkin

gen het meest effectief wanneer elke referentieafbeelding een duidelijke rol heeft. 

Paletreferenties werken goed wanneer de prompt expliciet “alleen palet” zegt en vermijdt het model te instrueren de referentie-inhoud als vervanging te gebruiken. 

Wanneer referenties dubbelzinnig zijn, kan het model in plaats van alleen kleur ook textuur- of lay-outsignalen overnemen.  In mijn run zag ik enkele kleine artefacten waarbij elementen die leken op de referentieafbeeldingen subtiel in de scène doordrongen, maar het geheel zag er nog steeds sterk en visueel consistent uit.

Een praktisch voordeel van deze demo is dat elke gegenereerde en bewerkte afbeelding in de sessiegeschiedenis wordt opgeslagen. Je kunt elke vorige entry laden en vanaf dat exacte checkpoint verder bewerken. Dit maakt experimenteren veel sneller. Je kunt bewerkingen vertakken vanaf een eerdere versie, meerdere richtingen vergelijken en voorkomen dat je een goed tussentijds resultaat kwijtraakt. 

Conclusie

In deze tutorial hebben we een complete workflow voor generatie en beeldbewerking gebouwd met FLUX.2 Klein 4B. Door lokale text-to-image-generatie met Diffusers te combineren met de gehoste bewerkings-API van Black Forest Labs, konden we een interactieve image-editor maken.

De lage latentie, geïntegreerde generatie- en bewerkingsmogelijkheden en multi-referentieondersteuning van FLUX.2 Klein maken het bijzonder geschikt voor dit soort interactieve workflow. Vanaf hier kun je de app uitbreiden met batchbewerking, parameterbesturing, persistentie over sessies of zelfs een LLM-gestuurde agent die automatisch bewerkingen voorstelt.