Tutorial de FLUX.2 Klein: Creación de una aplicación para generar y editar imágenes con Gradio

Paso 1: Configuración del entorno

Antes de crear nuestra aplicación de generación y edición de imágenes, necesitamos configurar un entorno limpio con la última biblioteca Diffusers. Para este tutorial, ejecutaremos todo en una instancia de Google Colab con una GPU A100 para generar imágenes más rápidamente. Dicho esto, la misma configuración también funciona en GPU más modestas, como una T4, con un rendimiento ligeramente más lento.

Empezamos desinstalando cualquier versión existente de Diffusers para evitar conflictos entre versiones y, a continuación, instalamos la última versión de desarrollo directamente desde GitHub. También instalamos las bibliotecas de apoyo necesarias para la carga de modelos, la gestión de puntos de control y la aceleración.

!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 vez completada la instalación, comprobamos la versión de Diffusers instalada y confirmamos que la clase Flux2KleinPipeline se puede importar correctamente.

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

Esto confirma que nuestro entorno está correctamente configurado. En el siguiente paso, cargaremos el modelo FLUX.2 Klein en la GPU y lo prepararemos tanto para la generación de imágenes locales como para los flujos de trabajo de edición basados en API.

Paso 2: Cargar FLUX.2 Klein 4B 

Antes de cargar el modelo, necesitas una clave API de Black Forest Labs. Para empezar, inicia sesión en tu cuenta de Black Forest Labs y añade créditos en la pestaña « » (Gestiónde créditos). La recarga mínima es de unos diez dólares, lo que da aproximadamente mil créditos. Una vez añadidos los créditos, haz clic en« » (Crear clave), asígnale un nombre descriptivo y guárdala en un lugar seguro.

Una vez que tengas tu clave API lista, el siguiente paso es cargar el modelo FLUX.2 Klein 4B y prepararlo para dos modos de uso diferentes: generación de imágenes locales y edición de imágenes basada en 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")

Empezamos configurando la clave API como un secreto de Colab, para que nunca aparezca en el código del cuaderno. También definimos el ID del modelo y el punto final de edición Klein que llamaremos más adelante. 

A continuación, aplicamos nest_asyncio antes de iniciar la interfaz de usuario de Gradio para evitar que se produzcan conflictos en el bucle de eventos.

Por último, carga el pipeline local FLUX.2 Klein para la generación de la imagen base. Utilizamos Flux2KleinPipeline con float16 para una amplia compatibilidad con GPU (tanto A100 como T4 funcionan bien) y, a continuación, trasladamos el proceso a CUDA para una inferencia rápida. Este canal local solo se utiliza para generar la imagen inicial, mientras que las ediciones se gestionan a través de la API.

Nota: En este punto, es posible que te preguntes por qué cargamos el modelo localmente y también configuramos el acceso a la API. La razón es la separación de capacidades:

• El canal local Hugging Face es ideal para la generación iterativa de texto a imagen y el control total sobre los ajustes de inferencia.
• La API de Black Forest Labs ofrece funciones avanzadas de edición de imágenes para FLUX.2 Klein que actualmente no están disponibles en la implementación de peso abierto, como ediciones de imágenes basadas en indicaciones con múltiples imágenes de referencia.

Al combinar ambos enfoques, obtenemos lo mejor de ambos mundos: velocidad de generación local y soporte para la edición.

Paso 3: Funciones auxiliares

Antes de conectar todo a la interfaz Gradio, necesitamos un pequeño conjunto de funciones auxiliares. Dado que nuestra aplicación genera imágenes localmente pero las edita a través de la API, necesitamos una forma de codificar las imágenes en base64 para las solicitudes de la API, una forma de descargar las imágenes editadas que se devuelven como URL y una función de generación local que produzca la imagen base inicial.

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

El código anterior define tres funciones auxiliares clave:

• La función pil_to_b64_png() convierte una imagen PIL en una cadena PNG codificada en base64. Esto es necesario porque la API de edición de FLUX.2 acepta la imagen base y las imágenes de referencia como URL o cadenas base64. 
• La función url_to_pil() se encarga de la dirección opuesta. La API de edición devuelve una URL firmada para la salida generada, por lo que obtenemos esa URL con requests, validamos la respuesta y convertimos los bytes descargados de nuevo en una imagen PIL. Esto permite que el resultado editado se muestre directamente en nuestra interfaz Gradio y se guarde en el historial.
• Por último, la función local_generate() es tu punto de entrada local de texto a imagen. Comprueba que el mensaje no esté vacío y, a continuación, llama a la función local « Flux2KleinPipeline » con ajustes fijos, como la resolución, el número de pasos y la escala de orientación. El resultado se devuelve como una imagen PIL RGB limpia, que se convierte en la imagen base para las ediciones posteriores.

No dudes en probar diferentes ajustes de la canalización FLUX, como la resolución de la imagen, los pasos de difusión y la escala de orientación, para explorar diferentes combinaciones de calidad y velocidad y comprender mejor cómo influye cada parámetro en la imagen final. 

La documentación de edición de imágenes de Flux 2 es es un buen lugar para comprender mejor estos ajustes.

En el siguiente paso, utilizaremos estas utilidades para implementar la edición de imágenes basada en API con FLUX.2 Klein.

Paso 4: Edición a través de la API de BFL

Este paso es la diferencia fundamental entre un flujo de trabajo puramente Hugging Face y el enfoque híbrido utilizado en este tutorial. En lugar de intentar ejecutar la edición de imágenes localmente, delegamos las ediciones a la API, que gestiona de forma fiable las ediciones basadas en indicaciones y el acondicionamiento multirreferencial opcional.

A alto nivel, la API de edición FLUX.2 Klein espera una indicación de texto que describa la edición, una imagen base para modificar e imágenes de referencia opcionales proporcionadas como entradas adicionales. La API se ejecuta de forma asíncrona, lo que significa que enviamos una solicitud y luego consultamos una URL devuelta hasta que la imagen editada está lista.

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 función ` bfl_edit() ` realiza tres tareas importantes:

• Requiere tres entradas: la indicación de edición, la imagen base que deseas modificar y una lista opcional de imágenes de referencia. 
• Creamos una carga JSON con la solicitud de edición y la imagen base codificada como un PNG de base64. Si se proporcionan imágenes de referencia, las adjuntamos utilizando el formato indexado de la API. Esto nos permite proporcionar hasta tres imágenes de referencia junto con la imagen base, lo cual es suficiente para muchos flujos de trabajo prácticos, como la transferencia de paletas de colores, el anclaje de estilos o la fijación de objetos.
• A continuación, enviamos la solicitud al punto final de la API y analizamos la respuesta. La API devuelve un objeto de estado de trabajo ( polling_url ) que debemos consultar repetidamente hasta que finalice el trabajo. Implementamos esto utilizando un sencillo bucle de sondeo con dos barreras de seguridad: un intervalo de sondeo que evita solicitudes excesivas y un tiempo de espera que impide que el portátil espere indefinidamente.

Una vez que el estado pasa a ser « Ready » (Imagen generada), la respuesta de la API contiene una URL firmada a la imagen de salida. Descargamos esa imagen utilizando nuestra función auxiliar url_to_pil() anterior y la devolvemos como una imagen PIL.

En el siguiente paso, implementaremos el historial de sesiones para que los usuarios puedan volver a visitar cualquier salida generada o editada.

Paso 5: Añadir historial 

En este punto, la última pieza que necesitamos antes de crear la interfaz de usuario es una capa de memoria de sesión ligera para que los usuarios puedan volver a consultar resultados anteriores. Implementamos el historial utilizando dos objetos de estado Gradio:

• base_img_state Almacena la imagen de trabajo actual (la imagen a la que se aplicarán las futuras ediciones).
• history_state almacena cada versión generada o editada como una lista de diccionarios, cada uno de los cuales contiene una imagen y una breve etiqueta.

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

Las funciones anteriores constituyen la lógica central para mantener el historial de imágenes en nuestra demostración:

• La función update_history() formatea el historial de la sesión en un menú desplegable. Cada entrada está etiquetada con su índice y una breve descripción, y el menú desplegable selecciona automáticamente el elemento más reciente de forma predeterminada. Esto mantiene la interfaz de usuario sincronizada sin necesidad de utilizar una lógica de actualización manual.
• La llamada de retorno ` on_generate() ` ejecuta ` local_generate() ` para crear la imagen base inicial. A continuación, añade el resultado al historial como {"img": img, "label": "Generated Base"}. La función devuelve tanto la imagen como el estado actualizado del historial, junto con una actualización desplegable para que la nueva entrada sea visible de inmediato.
• La llamada de retorno ` on_edit() ` es similar, pero en su lugar llama a ` bfl_edit() `. Toma la imagen de trabajo actual y algunas imágenes de referencia opcionales, aplica la edición a través de la API y añade el resultado al historial. También devuelve la salida editada como la nueva imagen base_img_state, lo que significa que las ediciones futuras se aplicarán a la imagen más reciente, a menos que el usuario cargue explícitamente una versión anterior.
• La llamada de retorno on_load() analiza la entrada seleccionada en el menú desplegable, recupera la imagen correspondiente de history_state y vuelve a convertir esa imagen en la imagen de trabajo activa. Esto permite a los usuarios bifurcar sus ediciones desde cualquier punto de control anterior.
• Por último, la función « on_clear() » restablece todo. Borra la salida, borra el estado de la imagen base, restablece la lista del historial y vacía las opciones del menú desplegable.

Conectemos estas funciones a una interfaz Gradio con dos cuadros de texto, cargas de referencias opcionales y un flujo de trabajo de historial.

Paso 6: Gradio UI

Este paso conecta nuestra lógica de generación, edición e historial a una sencilla interfaz Gradio. La interfaz está construida con gr.Blocks, lo que nos permite controlar con gran precisión el diseño. 

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)

Organizamos la interfaz de usuario en dos columnas, de modo que la columna izquierda contiene entradas y acciones, mientras que la columna derecha muestra la imagen actual. Así es como creamos la aplicación Gradio:

• El primer cuadro de texto recopila la solicitud de generación, y el botón«Generate Base Image» (Generarimagen base) activa la función « on_generate() » (Generar imagen base). Esta llamada de retorno ejecuta la generación local, guarda el resultado en el historial y actualiza tanto la imagen mostrada como la imagen de trabajo actual almacenada en base_img_state.
• El segundo cuadro de texto recopila una solicitud de instrucciones de edición. Cuando tú haces clicen « » (Aplicar edición), llamamos a la función « on_edit() », que utiliza la imagen de trabajo actual como imagen base y devuelve el resultado editado. La salida editada también se añade al historial y se convierte en la nueva imagen de trabajo para las próximas ediciones.
• Para que el flujo de trabajo tenga en cuenta las sesiones, también incluimos un menú desplegableHistorial de sesiones, de modo que cada entrada corresponda a una versión guardada de la imagen. El botón« » (Cargar imagen seleccionada ) activa la función « on_load() » (Cargar imagen del historial), que restaura la imagen seleccionada del historial y la establece de nuevo como imagen de trabajo actual. 
• Por último, el botón Borrar todo restablece todo mediante la función « on_clear() » (Restablecer estado predeterminado), incluyendo la pantalla de salida, el estado de la imagen base y el historial almacenado.

Los siguientes dos objetos Gradio State mantienen todo coherente:

• base_img_state asegura que cada edición se aplique a la imagen correcta.
• history_state Almacena la cronología completa de los resultados para su reproducción y ramificación.

Por último, demo.launch() inicia la aplicación en Colab, proporciona un enlace compartible, la representa en línea y habilita los registros de depuración para ayudar a diagnosticar problemas durante el desarrollo.

FLUX.2 Klein Ejemplos y observaciones

Para comprender cómo se comporta FLUX.2 Klein en la práctica. Realicé una serie de pequeños experimentos utilizando la aplicación Generate and Edit final. Probé tres patrones de interacción principales: generación de imágenes base, edición solo con indicaciones y edición guiada por referencias utilizando una o más imágenes. También he validado el flujo de trabajo del historial de sesiones para confirmar que puedo restaurar cualquier resultado anterior y continuar editando desde ese punto.

Generación de imágenes

Empecé con una sencilla indicación de generación para crear una imagen base limpia. El modelo produjo un sujeto coherente con una iluminación uniforme, detalles faciales nítidos y una disposición estable de la escena. La imagen base resultante parecía sólida y útil para modificaciones posteriores, más que para una regeneración.

Edición de imágenes con una sola imagen de referencia

A continuación, probé una sola imagen de referencia como fuente de color y utilicé una instrucción de edición del tipo «Cambia el color del vestido al color de la imagen de referencia». La edición transfirió con éxito el color deseado, conservando la mayor parte de la estructura original de la escena.

Según mi observación, las ediciones de referencia única funcionan mejor cuando la indicación es limitada y restringida. La transferencia de color y el cambio de color del vestuario son especialmente fiables, ya que no requieren cambios geométricos importantes. Cuando la instrucción de edición se centra en un solo atributo, la identidad del sujeto y los detalles del fondo permanecen estables.

Edición de imágenes con una sola indicación

Luego probé la edición solo con indicaciones con un cambio semántico, como «Reemplazar el fondo por una playa». El modelo gestionó la sustitución del fondo de forma limpia, al tiempo que mantuvo el sujeto más o menos consistente. 

Cuando cambia el fondo, el modelo suele ajustar la temperatura del color y la intensidad de las sombras para mantener el resultado fotorrealista. Esto suele ser una característica, pero significa que la imagen editada puede parecer una sesión fotográfica diferente en lugar de un simple cortar y pegar.

Guía para las posturas

Probé una edición basada en poses utilizando una imagen de referencia que sugiere la posición del cuerpo, combinada con una indicación como «Iguala la pose de la imagen de referencia». La imagen resultante cambió la pose del sujeto, pero mantuvo una identidad y un estilo similares.

Aquí está la imagen de referencia que usé como guía para la pose:

Las ediciones de pose son factibles, pero son más delicadas que las ediciones de color. Cualquier cambio de postura puede provocar cambios secundarios, como el drapeado de la tela, la colocación de las extremidades y el encuadre de la cámara. Me llevó un par de intentos conseguir esta postura, y aún así seguía teniendo problemas con la colocación de las piernas.

Edición de imágenes con múltiples imágenes de referencia

Por último, probé las ediciones multirreferencia utilizando varias entradas, como una referencia de paleta de colores y una indicación de edición que establece explícitamente «Cambiar solo los colores de fondo utilizando la paleta de las imágenes de referencia». No sustituyas el fondo por las imágenes de referencia. 

Para mi sorpresa, la edición multirreferencia...

g es más eficaz cuando cada imagen de referencia tiene una función clara. 

Las referencias de paleta funcionan bien cuando la indicación dice explícitamente «solo paleta» y evita indicar al modelo que utilice el contenido de referencia como sustituto. 

Cuando las referencias son ambiguas, el modelo puede tomar prestadas pistas de textura o diseño en lugar de solo color.  Durante mi prueba, observé algunos artefactos menores en los que elementos similares a las imágenes de referencia se colaban sutilmente en la escena, pero el resultado general seguía siendo sólido y visualmente coherente.

Una ventaja práctica de esta demostración es que todas las imágenes generadas y editadas se almacenan en el historial de la sesión. Puedes cargar cualquier entrada anterior y continuar editando desde ese punto exacto. Esto hace que la experimentación sea mucho más rápida. Puedes bifurcar las ediciones de una versión anterior, comparar múltiples direcciones de edición y evitar perder un buen resultado intermedio. 

Conclusión

En este tutorial, hemos creado un flujo de trabajo completo de generación y edición de imágenes utilizando FLUX.2 Klein 4B. Al combinar la generación local de texto a imagen mediante Diffusers con la API de edición alojada de Black Forest Labs, pudimos crear un editor de imágenes interactivo.

FLUX.2 Las capacidades de generación y edición unificadas y de baja latencia de Klein, así como su compatibilidad con múltiples referencias, lo hacen especialmente adecuado para este tipo de flujo de trabajo interactivo. Desde aquí, puedes ampliar la aplicación con edición por lotes, controles de parámetros, persistencia entre sesiones o incluso un agente impulsado por LLM que propone ediciones automáticamente.