FLUX.2 Klein Tutorial: Criando um aplicativo para gerar e editar imagens com o Gradio

Passo 1: Configuração do ambiente

Antes de criarmos nosso aplicativo de geração e edição de imagens, precisamos configurar um ambiente limpo com a biblioteca Diffusers mais recente. Neste tutorial, vamos rodar tudo em uma instância do Google Colab com uma GPU A100 pra gerar imagens mais rápido. Dito isso, a mesma configuração também funciona em GPUs mais modestas, como uma T4, com um desempenho um pouco mais lento.

Começamos desinstalando qualquer versão existente do Diffusers para evitar conflitos de versão e, em seguida, instalamos a versão de desenvolvimento mais recente diretamente do GitHub. Também instalamos as bibliotecas de suporte necessárias para carregamento de modelos, gerenciamento de pontos de verificação e aceleração.

!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

Quando a instalação estiver pronta, a gente dá uma olhada na versão do Diffusers que foi instalada e confirma se a classe Flux2KleinPipeline pode ser importada sem problemas.

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

Isso mostra que nosso ambiente está configurado da maneira certa. Na próxima etapa, vamos carregar o modelo FLUX.2 Klein na GPU e prepará-lo tanto para a geração de imagens locais quanto para fluxos de trabalho de edição baseados em API.

Passo 2: Load FLUX.2 Klein 4B 

Antes de carregar o modelo, você precisa de uma chave API da Black Forest Labs. Pra começar, entra na tua conta conta do Black Forest Labs e adicione créditos na aba Créditos. O recarga mínima é de cerca de dez dólares, o que dá mais ou menos mil créditos. Depois de adicionar os créditos, clique em“ ”(Criar chave), dê um nome descritivo e guarde-a em um lugar seguro.

Com sua chave API pronta, o próximo passo é carregar o modelo FLUX.2 Klein 4B e prepará-lo para dois modos de uso diferentes: geração de imagens locais e edição de imagens baseada em 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")

Começamos configurando a chave API como um segredo do Colab, para que ela nunca apareça no código do notebook. Também definimos o ID do modelo e o ponto final de edição Klein que chamaremos mais tarde. 

Depois, a gente aplica um nest_asyncio o antes de abrir a interface do Gradio pra evitar conflitos no loop de eventos.

Por fim, carregue o pipeline local FLUX.2 Klein para gerar a imagem base. Usamos Flux2KleinPipeline com float16 para uma ampla compatibilidade com GPU (A100 e T4 funcionam bem), depois mudamos o pipeline para CUDA para uma inferência rápida. Esse pipeline local é usado só pra gerar a imagem inicial, enquanto as edições são feitas pela API.

Observação: Neste ponto, você pode estar se perguntando por que carregamos o modelo localmente e também configuramos o acesso à API. O motivo é a separação de capacidades:

• O pipeline local do Hugging Face é ideal para gerar texto para imagem de forma iterativa e ter controle total sobre as configurações de inferência.
• A API do Black Forest Labs oferece recursos avançados de edição de imagens para o FLUX.2 Klein que ainda não estão disponíveis na versão aberta, como edições de imagens baseadas em prompts com várias imagens de referência.

Ao juntar as duas abordagens, a gente consegue o melhor dos dois mundos: velocidade de geração local e suporte à edição.

Passo 3: Funções auxiliares

Antes de conectar tudo na interface Gradio, precisamos de um pequeno conjunto de funções auxiliares. Como nosso aplicativo gera imagens localmente, mas as edita por meio da API, precisamos de uma maneira de codificar imagens em base64 para solicitações de API, uma maneira de baixar imagens editadas retornadas como URLs e uma função de geração local que produza a imagem 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")

O código acima define três funções auxiliares importantes:

• A função pil_to_b64_png() transforma uma imagem PIL numa sequência PNG codificada em base64. Isso é necessário porque a API de edição do FLUX.2 aceita a imagem base e as imagens de referência como URLs ou strings base64. 
• A função ` url_to_pil() ` cuida da direção oposta. A API de edição devolve uma URL assinada para a saída gerada, então a gente pega essa URL com requests, valida a resposta e converte os bytes baixados de volta em uma imagem PIL. Isso permite que o resultado editado seja mostrado direto na nossa interface Gradio e salvo no histórico.
• Por fim, a função local_generate() é o nosso ponto de entrada local para conversão de texto em imagem. Ele verifica se o prompt não está vazio e, em seguida, chama o Flux2KleinPipeline local com configurações fixas, como resolução, contagem de passos e escala de orientação. A saída é devolvida como uma imagem PIL RGB limpa, que se torna a imagem base para edições posteriores.

Fique à vontade para brincar com as configurações do pipeline FLUX, como resolução da imagem, etapas de difusão e escala de orientação, para explorar diferentes combinações de qualidade e velocidade e entender melhor como cada parâmetro influencia a imagem final. 

A documentação de edição de imagens do Flux 2 é um bom lugar pra entender mais sobre essas configurações. é um bom lugar para entender mais sobre essas configurações.

Na próxima etapa, vamos usar esses utilitários para implementar a edição de imagens baseada em API com o FLUX.2 Klein.

Passo 4: Editando através da API BFL

Essa etapa é a principal diferença entre um fluxo de trabalho puramente Hugging Face e a abordagem híbrida usada neste tutorial. Em vez de tentar editar imagens localmente, a gente passa as edições para a API, que cuida das edições baseadas em prompts e do condicionamento opcional de múltiplas referências de forma confiável.

Em um nível mais alto, a API de edição FLUX.2 Klein espera um prompt de texto descrevendo a edição, uma imagem base para modificar e imagens de referência opcionais fornecidas como entradas adicionais. A API funciona de forma assíncrona, ou seja, a gente manda uma solicitação e depois fica checando uma URL devolvida até que a imagem editada esteja 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}")

A função ` bfl_edit() ` faz três coisas importantes:

• São necessárias três entradas, incluindo o prompt de edição, a imagem base que queremos modificar e uma lista opcional de imagens de referência. 
• A gente cria uma carga JSON com o prompt de edição e a imagem base codificada como um PNG base64. Se forem fornecidas imagens de referência, nós as anexamos usando o formato indexado da API. Isso nos permite fornecer até três imagens de referência junto com a imagem base, o que é suficiente para muitos fluxos de trabalho práticos, como transferência de paleta de cores, fixação de estilo ou aterramento de objetos.
• Depois, mandamos a solicitação para o endpoint da API e analisamos a resposta. A API retorna um objeto ` polling_url ` que a gente precisa consultar várias vezes até o trabalho terminar. Implementamos isso usando um loop de polling simples com duas proteções: um intervalo de polling que evita solicitações excessivas e um tempo limite que impede que o notebook fique esperando indefinidamente.

Quando o status passar para “ Ready ”, a resposta da API vai ter um URL assinado para a imagem de saída. Baixamos essa imagem usando nossa função auxiliar url_to_pil() anterior e a devolvemos como uma imagem PIL.

Na próxima etapa, vamos implementar o histórico de sessão para que os usuários possam revisitar qualquer saída gerada ou editada.

Passo 5: Adicionando histórico 

Neste ponto, a última peça que precisamos antes de construir a interface do usuário é uma camada de memória de sessão leve para que os usuários possam revisitar resultados anteriores. Implementamos o histórico usando dois objetos de estado Gradio:

• base_img_state armazena a imagem atual em que você está trabalhando (a imagem que as edições futuras vão afetar).
• history_state armazena cada versão gerada ou editada como uma lista de dicionários, cada um com uma imagem e uma pequena 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."

As funções acima são a lógica principal para manter o histórico de imagens na nossa demonstração:

• A função ` update_history() ` transforma o histórico da sessão em um menu suspenso. Cada entrada tem um índice e uma breve descrição, e o menu suspenso seleciona automaticamente o item mais recente por padrão. Isso mantém a interface do usuário sincronizada sem precisar atualizar manualmente.
• A chamada de retorno ` on_generate() ` executa ` local_generate() ` para criar a imagem base inicial. Em seguida, ele adiciona o resultado ao histórico como {"img": img, "label": "Generated Base"}. A função retorna tanto a imagem quanto o estado atualizado do histórico, junto com uma atualização do menu suspenso para que a nova entrada fique visível imediatamente.
• A chamada de retorno ` on_edit() ` é parecida, mas chama ` bfl_edit() ` em vez disso. Pega a imagem atual em que você está trabalhando e algumas imagens de referência opcionais, faz a edição pela API e adiciona o resultado ao histórico. Ele também retorna a saída editada como a nova imagem base_img_state, o que significa que as edições futuras serão aplicadas à imagem mais recente, a menos que o usuário carregue explicitamente uma versão mais antiga.
• A chamada de retorno on_load() analisa a entrada selecionada no menu suspenso, pega a imagem correspondente em history_state e faz com que essa imagem volte a ser a imagem ativa. Isso permite que os usuários ramifiquem suas edições a partir de qualquer ponto de verificação anterior.
• Por fim, a função ` on_clear() ` reinicia tudo. Limpa a saída, limpa o estado da imagem base, reinicia a lista de histórico e esvazia as opções do menu suspenso.

Vamos conectar essas funções a uma interface Gradio com duas caixas de texto, uploads de referência opcionais e um fluxo de trabalho de histórico.

Passo 6: Interface do usuário do Gradio

Essa etapa conecta nossa lógica de geração, edição e histórico a uma interface Gradio simples. A interface foi criada com gr.Blocks, que nos permite controlar o layout com precisã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 a interface do usuário em duas colunas, de forma que a coluna esquerda tenha entradas e ações, enquanto a coluna direita mostra a imagem atual. Veja como criamos o aplicativo Gradio:

• A primeira caixa de texto coleta o prompt de geração, e o botão“Gerar imagem base” ( ) aciona a função “Gerarimagem base” ( on_generate() ). Essa chamada de retorno executa a geração local, salva a saída no histórico e atualiza tanto a imagem exibida quanto a imagem de trabalho atual armazenada em base_img_state.
• A segunda caixa de texto pega uma mensagem de instrução de edição. Quando o usuário clicaem “ ” (Aplicar edição), “Apply Edit” (Aplicar edição), “ ” (Imagem editada), chamamos a função “ on_edit() ” (Aplicar edição), que usa a imagem atual como imagem base e retorna a saída editada. A saída editada também é adicionada ao histórico e vira a nova imagem de trabalho para as próximas edições.
• Para tornar o fluxo de trabalho sensível à sessão, também incluímos um menu suspensoHistórico da sessão, de modo que cada entrada corresponda a uma versão salva da imagem. O botão“Carregar selecionado” ( ) aciona o comando “Carregar imagem selecionada” ( on_load()), que restaura a imagem selecionada do histórico e a define novamente como a imagem de trabalho atual. 
• Por fim, o botão Limpar tudo apaga tudo usando a função “ on_clear() ”, incluindo a exibição de saída, o estado da imagem base e o histórico armazenado.

Os dois objetos Gradio State a seguir mantêm tudo consistente:

• base_img_state garante que cada edição seja aplicada à imagem certa.
• history_state Armazena a linha do tempo completa das saídas para reprodução e ramificação.

Por fim, demo.launch() lança o aplicativo no Colab, fornece um link compartilhável, o renderiza em linha e habilita logs de depuração para ajudar a diagnosticar problemas durante o desenvolvimento.

FLUX.2 Klein Exemplos e observações

Para entender como o FLUX.2 Klein funciona na prática. Fiz umas pequenas experiências usando o aplicativo final Generate and Edit. Testei três padrões principais de interação: geração de imagem base, edição apenas por prompt e edição guiada por referência usando uma ou mais imagens. Também dei uma olhada no histórico da sessão pra ter certeza de que posso recuperar qualquer resultado anterior e continuar editando a partir daí.

Geração de imagens

Comecei com um prompt de geração simples para criar uma imagem base limpa. O modelo produziu um objeto coerente com iluminação consistente, detalhes faciais nítidos e um layout de cena estável. A imagem base resultante parecia forte e útil para modificações posteriores, em vez de uma regeneração.

Edição de imagens com uma única imagem de referência

Depois, testei uma única imagem de referência como fonte de cor e usei uma instrução de edição tipo “Mude a cor do vestido para a cor da imagem de referência”. A edição conseguiu passar a cor que a gente queria, mantendo a maior parte da estrutura original da cena.

Pela minha experiência, as edições de referência única funcionam melhor quando a solicitação é específica e limitada. A transferência de cores e a recoloração do guarda-roupa são especialmente confiáveis porque não exigem grandes mudanças na geometria. Quando a instrução de edição se concentra em um atributo, a identidade do assunto e os detalhes do contexto permanecem estáveis.

Edição de imagens com um único comando

Então, tentei editar só com o prompt com uma mudança semântica, tipo “Trocar o fundo por uma praia”. O modelo fez a substituição do fundo direitinho, mantendo o objeto mais ou menos igual. 

Quando o fundo muda, o modelo geralmente ajusta a temperatura da cor e a intensidade da sombra para manter o resultado fotorrealista. Isso geralmente é uma característica, mas significa que a imagem editada pode parecer uma sessão de fotos diferente, em vez de um simples recorte e colagem.

Orientação sobre poses

Testei uma edição baseada em poses usando uma imagem de referência que mostra o posicionamento do corpo, junto com uma sugestão tipo “Combine uma pose com uma imagem de referência”. A imagem resultante mudou a pose do sujeito, mas manteve uma identidade e um estilo parecidos.

Aqui tá a imagem que usei como referência pra orientar a pose:

As edições de pose são possíveis, mas são mais delicadas do que as edições de cor. Qualquer mudança de pose pode causar mudanças secundárias, como o caimento do tecido, a posição dos membros e o enquadramento da câmera. Levei algumas tentativas pra acertar essa pose, e ainda tava com dificuldade pra posicionar as pernas.

Edição de imagens com várias imagens de referência

Por fim, testei edições com várias referências usando várias entradas, como uma referência de paleta de cores e um prompt de edição que diz explicitamente “Mude só as cores de fundo usando a paleta das imagens de referência”. Não troque o fundo pelas imagens de referência. 

Pra minha surpresa, a edição com várias referências

O g é mais eficaz quando cada imagem de referência tem uma função clara. 

As referências de paleta funcionam bem quando o prompt diz explicitamente “apenas paleta” e evita instruir o modelo a usar o conteúdo de referência como substituto. 

Quando as referências são meio confusas, o modelo pode pegar emprestadas dicas de textura ou layout, em vez de só cor.  Na minha execução, notei alguns pequenos artefatos em que elementos parecidos com as imagens de referência apareceram sutilmente na cena, mas o resultado geral ainda parecia forte e visualmente consistente.

Uma vantagem prática dessa demonstração é que todas as imagens geradas e editadas ficam guardadas no histórico da sessão. Você pode carregar qualquer entrada anterior e continuar editando a partir desse ponto exato. Isso torna a experimentação muito mais rápida. Você pode ramificar edições de uma versão anterior, comparar várias direções de edição e evitar perder um bom resultado intermediário. 

Conclusão

Neste tutorial, criamos um fluxo de trabalho completo de geração e edição de imagens usando o FLUX.2 Klein 4B. Combinando a geração local de texto para imagem através do Diffusers com a API de edição hospedada pela Black Forest Labs, conseguimos criar um editor de imagens interativo.

FLUX.2 As capacidades de geração e edição unificadas e de baixa latência do Klein, além do suporte a múltiplas referências, tornam-no particularmente adequado para este tipo de fluxo de trabalho interativo. A partir daqui, você pode expandir o aplicativo com edição em lote, controles de parâmetros, persistência entre sessões ou até mesmo um agente baseado em LLM que sugere edições automaticamente.