Tutoriel FLUX.2 Klein : Développement d'une application de génération et d'édition d'images avec Gradio

Étape 1 : Configuration de l'environnement

Avant de développer notre application de génération et d'édition d'images, il est nécessaire de configurer un environnement propre avec la dernière bibliothèque Diffusers. Pour ce tutoriel, nous exécuterons l'ensemble du processus sur une instance Google Colab équipée d'un GPU A100 afin d'accélérer la génération des images. Cela dit, la même configuration fonctionne également sur des GPU plus modestes, tels que le T4, avec des performances légèrement inférieures.

Nous commençons par désinstaller toute version existante de Diffusers afin d'éviter tout conflit de versions, puis nous installons la dernière version de développement directement depuis GitHub. Nous installons également les bibliothèques de support nécessaires au chargement des modèles, à la gestion des points de contrôle et à l'accélération.

!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

Une fois l'installation terminée, nous vérifions la version de Diffusers installée, puis nous nous assurons que la classe Flux2KleinPipeline peut être importée avec succès.

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

Ceci confirme que notre environnement est correctement configuré. Dans l'étape suivante, nous chargerons le modèle FLUX.2 Klein sur le GPU et le préparerons à la fois pour la génération d'images locales et les workflows d'édition basés sur l'API.

Étape 2 : Charger FLUX.2 Klein 4B 

Avant de charger le modèle, il est nécessaire d'obtenir une clé API auprès de Black Forest Labs. Pour commencer, veuillez vous connecter à votre compte Black Forest Labs et ajoutez des crédits dans l'onglet «Crédits ». Le montant minimum de recharge est d'environ dix dollars, ce qui donne droit à environ mille crédits. Une fois les crédits ajoutés, veuillez cliquer sur «Créer une clé » ( ), attribuez-lui un nom descriptif et conservez-la en lieu sûr.

Une fois votre clé API prête, l'étape suivante consiste à charger le modèle FLUX.2 Klein 4B et à le préparer pour deux modes d'utilisation différents : la génération d'images locales et l'édition d'images basée sur l'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")

Nous commençons par configurer la clé API en tant que secret Colab, afin qu'elle n'apparaisse jamais dans le code du notebook. Nous définissons également l'ID du modèle et le point final d'édition Klein que nous appellerons ultérieurement. 

Ensuite, nous appliquons l'nest_asyncio e avant de lancer l'interface utilisateur Gradio afin d'éviter de déclencher des conflits dans la boucle d'événements.

Enfin, veuillez charger le pipeline local FLUX.2 Klein pour la génération de l'image de base. Nous utilisons Flux2KleinPipeline avec float16 pour une compatibilité GPU étendue (A100 et T4 fonctionnent tous deux efficacement), puis transférons le pipeline vers CUDA pour une inférence rapide. Ce pipeline local est utilisé uniquement pour générer l'image initiale, tandis que les modifications sont gérées via l'API.

Remarque : À ce stade, vous pourriez vous demander pourquoi nous chargeons le modèle localement et configurons également l'accès à l'API. La raison en est la séparation des capacités :

• Le pipeline Hugging Face local est idéal pour la génération itérative de texte en image et le contrôle total des paramètres d'inférence.
• L'API Black Forest Labs offre des fonctionnalités avancées d'édition d'images pour FLUX.2 Klein qui ne sont actuellement pas disponibles dans la version open-weight, telles que les modifications d'images basées sur des invites avec plusieurs images de référence.

En combinant ces deux approches, nous bénéficions du meilleur des deux mondes : la rapidité de génération locale et l'assistance à l'édition.

Étape 3 : Fonctions d'assistance

Avant de connecter tous les éléments à l'interface Gradio, nous avons besoin d'un petit ensemble de fonctions d'aide. Étant donné que notre application génère des images localement mais les modifie via l'API, nous avons besoin d'un moyen d'encoder les images en base64 pour les requêtes API, d'un moyen de télécharger les images modifiées renvoyées sous forme d'URL et d'une fonction de génération locale qui produit l'image de base initiale.

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

Le code ci-dessus définit trois fonctions d'aide essentielles :

• La fonction pil_to_b64_png() convertit une image PIL en une chaîne PNG encodée en base64. Ceci est nécessaire car l'API d'édition FLUX.2 accepte l'image de base et les images de référence sous forme d'URL ou de chaînes base64. 
• La fonction ` url_to_pil() ` gère la direction opposée. L'API d'édition renvoie une URL signée pour la sortie générée. Nous récupérons donc cette URL avec requests, validons la réponse et convertissons les octets téléchargés en une image PIL. Cela permet d'afficher le résultat modifié directement dans notre interface Gradio et de l'enregistrer dans l'historique.
• Enfin, la fonction local_generate() constitue notre point d'entrée local pour la conversion de texte en image. Il vérifie que l'invite n'est pas vide, puis appelle l'Flux2KleinPipeline e locale avec des paramètres fixes tels que la résolution, le nombre d'étapes et l'échelle de guidage. Le résultat est renvoyé sous forme d'image PIL RVB propre, qui devient l'image de base pour les modifications ultérieures.

Nous vous invitons à explorer les paramètres du pipeline FLUX, tels que la résolution d'image, les étapes de diffusion et l'échelle de guidage, afin d'examiner différents compromis entre qualité et vitesse et de mieux comprendre comment chaque paramètre influence l'image finale. 

La documentation relative à l'édition d'images Flux 2 est un excellent outil pour approfondir vos connaissances sur ces paramètres. est un excellent moyen d'approfondir vos connaissances sur ces paramètres.

Dans l'étape suivante, nous utiliserons ces utilitaires pour mettre en œuvre l'édition d'images basée sur l'API avec FLUX.2 Klein.

Étape 4 : Modification via l'API BFL

Cette étape constitue la principale différence entre un workflow Hugging Face pur et l'approche hybride utilisée dans ce tutoriel. Au lieu de tenter d'effectuer l'édition d'images localement, nous déléguons les modifications à l'API, qui gère de manière fiable les modifications basées sur des invites et le conditionnement multi-références optionnel.

À un niveau élevé, l'API d'édition FLUX.2 Klein attend une invite textuelle décrivant la modification, une image de base à modifier et, éventuellement, des images de référence fournies en tant qu'entrées supplémentaires. L'API fonctionne de manière asynchrone, ce qui signifie que nous soumettons une demande, puis interrogeons une URL renvoyée jusqu'à ce que l'image modifiée soit prête.

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 fonction ` bfl_edit() ` effectue trois opérations importantes :

• Il nécessite trois entrées, à savoir l'invite d'édition, l'image de base que nous souhaitons modifier et une liste facultative d'images de référence. 
• Nous créons une charge utile JSON avec l'invite d'édition et l'image de base encodée au format PNG base64. Si des images de référence sont fournies, nous les joignons en utilisant le format indexé de l'API. Cela nous permet de fournir jusqu'à trois images de référence en plus de l'image de base, ce qui est suffisant pour de nombreux flux de travail pratiques tels que le transfert de palette de couleurs, l'ancrage de style ou l'ancrage d'objet.
• Ensuite, nous soumettons la requête au point de terminaison API et analysons la réponse. L'API renvoie une API de travail ( polling_url ) que nous devons interroger de manière répétée jusqu'à ce que le travail soit terminé. Nous mettons cela en œuvre à l'aide d'une simple boucle d'interrogation avec deux garde-fous : un intervalle d'interrogation qui évite les requêtes excessives et un délai d'attente qui empêche le notebook d'attendre indéfiniment.

Une fois que le statut passe à « Ready », la réponse API contient une URL signée vers l'image de sortie. Nous téléchargeons cette image à l'aide de notre fonction d'aide url_to_pil() précédemment mentionnée et la renvoyons sous forme d'image PIL.

Dans l'étape suivante, nous implémenterons l'historique des sessions afin que les utilisateurs puissent revoir toute sortie générée ou modifiée.

Étape 5 : Ajouter l'historique 

À ce stade, le dernier élément dont nous avons besoin avant de créer l'interface utilisateur est une couche mémoire de session légère afin que les utilisateurs puissent revoir les résultats précédents. Nous implémentons l'historique à l'aide de deux objets d'état Gradio :

• base_img_state enregistre l'image de travail actuelle (l'image à laquelle les modifications futures seront appliquées).
• history_state stocke chaque version générée ou modifiée sous forme de liste de dictionnaires, chacun contenant une image et une brève description.

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

Les fonctions ci-dessus constituent la logique centrale permettant de conserver l'historique des images dans notre démonstration :

• La fonction update_history() formate l'historique de session dans une liste déroulante. Chaque entrée est identifiée par son index et une brève description, et le menu déroulant sélectionne automatiquement l'élément le plus récent par défaut. Cela permet de synchroniser l'interface utilisateur sans nécessiter de logique de rafraîchissement manuel.
• La fonction de rappel ` on_generate() ` exécute ` local_generate() ` pour créer l'image de base initiale. Il ajoute ensuite le résultat à l'historique sous le nom {"img": img, "label": "Generated Base"}. La fonction renvoie à la fois l'image et l'état actualisé de l'historique, ainsi qu'une mise à jour du menu déroulant afin que la nouvelle entrée soit immédiatement visible.
• La fonction de rappel ` on_edit() ` est similaire, mais elle appelle plutôt ` bfl_edit() `. Il utilise l'image de travail actuelle et certaines images de référence facultatives, applique les modifications via l'API et ajoute le résultat à l'historique. Il renvoie également le résultat modifié en tant que nouvelle image ( base_img_state), ce qui signifie que les modifications futures s'appliqueront à l' la plus récente, à moins que l'utilisateur ne charge explicitement une version antérieure.
• La fonction de rappel on_load() analyse l'entrée sélectionnée dans la liste déroulante, récupère l'image correspondante à partir de history_state et rétablit cette image comme image de travail active. Cela permet aux utilisateurs de bifurquer leurs modifications à partir de n'importe quel point de contrôle précédent.
• Enfin, la fonction « on_clear() » réinitialise tout. Cela efface la sortie, efface l'état de l'image de base, réinitialise la liste d'historique et vide les choix du menu déroulant.

Intégrons ces fonctions dans une interface Gradio avec deux zones de texte, des téléchargements de références facultatifs et un historique des opérations.

Étape 6 : Interface utilisateur Gradio

Cette étape relie notre logique de génération, d'édition et d'historique à une interface Gradio simple. L'interface est développée à l'aide d'gr.Blocks, ce qui nous permet de contrôler précisément la mise en page. 

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)

Nous organisons l'interface utilisateur en deux colonnes, de sorte que la colonne de gauche contienne les entrées et les actions, tandis que la colonne de droite affiche l'image actuelle. Voici comment nous développons l'application Gradio :

• La première zone de texte recueille la demande de génération, et le bouton «Générer l'image de base » déclenche la fonction d'on_generate(). Cette fonction de rappel exécute la génération locale, enregistre le résultat dans l'historique et met à jour à la fois l'image affichée et l'image de travail actuelle stockée dans base_img_state.
• La deuxième zone de texte recueille une invite d'instruction d'édition. Lorsque l'utilisateur cliquesur « Appliquer les modifications » (Apply Edit) (), nous appelons la fonction «Appliquer les modifications » ( on_edit() ), qui utilise l'image de travail actuelle comme image de base et renvoie le résultat modifié. La sortie modifiée est également ajoutée à l'historique et devient la nouvelle image de travail pour les prochaines modifications.
• Afin de rendre le flux de travail sensible à la session, nous incluons également une liste déroulante intitulée «Historique de session » ( ) de sorte que chaque entrée corresponde à une version enregistrée de l'image. Le bouton «Load Selected » (Charger la sélection) de l' permet de déclencher l'on_load(), qui restaure l'image historique choisie et la définit à nouveau comme image de travail actuelle. 
• Enfin, le bouton Effacer tout réinitialise tout grâce à la fonction d'on_clear(), y compris l'affichage de la sortie, l'état de l'image de base et l'historique enregistré.

Les deux objets Gradio State suivants assurent la cohérence de l'ensemble :

• base_img_state garantit que chaque modification s'applique à l'image appropriée.
• history_state stocke l'historique complet des sorties pour la relecture et la ramification.

Enfin, demo.launch() lance l'application dans Colab, fournit un lien partageable, la rend en ligne et active les journaux de débogage pour aider à diagnostiquer les problèmes pendant le développement.

FLUX.2 Klein Exemples et observations

Pour comprendre comment FLUX.2 Klein se comporte dans la pratique. J'ai mené une série de petites expériences à l'aide de la version finale de l'application Generate and Edit. J'ai évalué trois principaux modèles d'interaction : la génération d'images de base, l'édition par invite uniquement et l'édition guidée par référence à l'aide d'une ou plusieurs images. J'ai également validé le flux de travail de l'historique des sessions afin de confirmer que je peux restaurer n'importe quelle sortie précédente et poursuivre l'édition à partir de ce point.

Génération d'images

J'ai commencé par une simple invite de génération afin de créer une image de base propre. Le modèle a produit un sujet cohérent avec un éclairage uniforme, des détails faciaux nets et une disposition stable de la scène. L'image de base obtenue semblait solide et utile pour des modifications ultérieures plutôt que pour une régénération.

Édition d'images à partir d'une seule image de référence

Ensuite, j'ai testé une seule image de référence comme source de couleur et j'ai utilisé une instruction de modification telle que « Veuillez modifier la couleur de la robe pour qu'elle corresponde à celle de l'image de référence ». La modification a permis de transférer avec succès la couleur souhaitée tout en conservant la majeure partie de la structure originale de la scène.

D'après mon observation, les modifications de référence unique fonctionnent mieux lorsque l'invite est restreinte et limitée. Le transfert de couleur et la recoloration de la garde-robe sont particulièrement fiables, car ils ne nécessitent pas de modifications géométriques importantes. Lorsque l'instruction d'édition se concentre sur un seul attribut, l'identité du sujet et les détails contextuels restent stables.

Modification d'images à l'aide d'une seule invite

Ensuite, j'ai tenté l'édition par invite uniquement avec une modification sémantique, telle que « Remplacer l'arrière-plan par une plage ». Le modèle a traité la substitution de l'arrière-plan de manière efficace, tout en conservant le sujet globalement cohérent. 

Lorsque l'arrière-plan change, le modèle ajuste souvent la température de couleur et l'intensité des ombres afin de conserver un résultat photoréaliste. Il s'agit généralement d'une fonctionnalité, mais cela signifie que l'image modifiée peut apparaître comme une photographie différente plutôt qu'un simple copier-coller.

Conseils pour les poses

J'ai testé une modification basée sur la pose à l'aide d'une image de référence suggérant une position du corps, combinée à une invite telle que « Reproduisez la pose de l'image de référence ». L'image obtenue a modifié la pose du sujet tout en conservant une identité et un style similaires.

Voici l'image de référence que j'ai utilisée pour guider la pose :

Les modifications de pose sont possibles, mais elles sont plus délicates que les modifications de couleur. Tout changement de pose peut entraîner des modifications secondaires telles que le drapé du tissu, le placement des membres et le cadrage de la caméra. Il m'a fallu plusieurs essais pour réussir cette pose, et j'ai encore rencontré des difficultés avec le placement des jambes.

Édition d'images à l'aide de plusieurs images de référence

Enfin, j'ai testé les modifications multi-références à l'aide de plusieurs entrées, telles qu'une référence de palette de couleurs et une invite de modification indiquant explicitement « Ne modifier les couleurs d'arrière-plan qu'à l'aide de la palette des images de référence ». Veuillez ne pas remplacer l'arrière-plan par les images de référence. 

À ma grande surprise, l'édition multi-références

g est particulièrement efficace lorsque chaque image de référence a un rôle bien défini. 

Les références de palette fonctionnent bien lorsque l'invite indique explicitement « palette uniquement » et évite de demander au modèle d'utiliser le contenu de référence comme remplacement. 

Lorsque les références sont ambiguës, le modèle peut emprunter des éléments de texture ou de mise en page plutôt que la couleur uniquement.  Au cours de mon essai, j'ai remarqué quelques artefacts mineurs où des éléments ressemblant aux images de référence se sont subtilement infiltrés dans la scène, mais le résultat global restait convaincant et visuellement cohérent.

Un avantage pratique de cette démonstration est que chaque image générée et modifiée est enregistrée dans l'historique de la session. Vous pouvez charger n'importe quelle entrée précédente et poursuivre la modification à partir de ce point précis. Cela accélère considérablement le processus d'expérimentation. Vous pouvez créer des branches à partir d'une version antérieure, comparer plusieurs directions d'édition et éviter de perdre un résultat intermédiaire satisfaisant. 

Conclusion

Dans ce tutoriel, nous avons mis en place un processus complet de génération et d'édition d'images à l'aide de FLUX.2 Klein 4B. En combinant la génération locale de texte en image via Diffusers avec l'API d'édition hébergée par Black Forest Labs, nous avons pu créer un éditeur d'images interactif.

FLUX.2 Les capacités de génération et d'édition unifiées à faible latence de Klein, ainsi que la prise en charge de plusieurs références, le rendent particulièrement adapté à ce type de flux de travail interactif. À partir de là, vous pouvez étendre les fonctionnalités de l'application avec l'édition par lots, les contrôles de paramètres, la persistance entre les sessions, ou même un agent piloté par LLM qui propose automatiquement des modifications.