FLUX 3 Image Klein: guia prático para imagens de referência, composição e edição local

Você tem uma foto de produto que serve, mas a composição não funciona para o próximo uso. O objeto precisa ir para a esquerda, o fundo deve mudar e o lado direito precisa continuar livre para uma manchete. Pedir para um gerador começar do zero é fácil. Conseguir uma revisão realmente aproveitável é mais difícil.

O FLUX 3 Image Klein reúne geração de imagens a partir de texto, edição e várias imagens de referência em uma família de modelos. A Black Forest Labs o lançou em 15 de outubro de 2026. A mudança interessante não é mais uma amostra bonita: é poder descrever tanto o conteúdo da imagem quanto a posição de cada elemento. Anúncio da BFL

Este guia leva você de um primeiro teste pequeno a um fluxo de edição repetível. Comece pelo navegador se quiser conhecer a ferramenta; escolha uma API para integrá-la a um aplicativo; considere a execução local quando o controle dos arquivos ou o uso frequente justificar a configuração. Não é preciso entender a matemática de difusão para escolher.

Escolha o caminho mais curto até uma primeira imagem útil

São produtos diferentes construídos em torno de pesos relacionados, não botões intercambiáveis. Um modelo é o conjunto de pesos aprendidos. Um runtime executa esse modelo. O ComfyUI oferece uma interface de fluxos de trabalho; o Diffusers fornece componentes Python; uma API hospedada oferece um serviço operado por terceiros. O recurso visto em uma interface pode depender de processamento que outra interface não faz.

Para começar, abra o Space oficial ou o BFL Playground. Confira eventuais avisos de conta e cobrança antes de gerar. O navegador é o mesmo ponto de partida no Windows, macOS e Linux; para usar um serviço remoto, você não precisa de uma GPU local.

Use uma imagem sua que possa ser enviada com segurança ao serviço. Uma foto da sua própria caneca é um material de aprendizado melhor do que um produto ainda não lançado de um cliente. O exercício a seguir propõe uma tarefa pequena e concreta e mostra como avaliar o resultado.

Faça uma alteração controlada antes de combinar dez referências

1. Salve uma cópia intacta da imagem original e anote suas dimensões.
2. Escolha um fluxo de edição e anexe somente essa imagem.
3. Descreva a cena desejada por inteiro, inclusive o que deve continuar reconhecível.
4. Peça uma alteração, como trocar o fundo, em vez de mudar ao mesmo tempo o objeto, o estilo e a composição.
5. Compare o resultado com o original em resolução total. Examine forma, texto, bordas e iluminação, não apenas a miniatura.
6. Guarde juntos a instrução e o resultado. Na próxima tentativa, altere uma variável.

Por exemplo, comece com esta descrição de cena:

A catalog photograph of the same plain ceramic mug from the reference image,
with its handle and proportions preserved, on a matte pale-green surface.
Soft light comes from the left. The mug sits in the left third of a wide
composition, leaving clear space on the right for text added later.

Os critérios de aceitação são seus: a alça não mudou, a silhueta da caneca continua útil e a área vazia está realmente livre. Se um logotipo precisar ser exato, compare-o com o original em vez de confiar em uma reconstrução que apenas parece plausível. Quando ortografia e geometria da marca forem inegociáveis, acrescente a tipografia final em uma ferramenta de design convencional.

O cartão oficial do modelo descreve suporte para até 10 imagens de referência. Isso é uma capacidade, não uma recomendação de usar dez em toda tarefa. Duas referências com ângulos de câmera conflitantes podem gerar mais ambiguidade do que uma referência limpa. Dê a cada entrada uma função específica: objeto, material, composição ou estilo.

Caixas de composição orientam o enquadramento, mas não fixam pixels

O FLUX 3 permite descrever regiões usando coordenadas normalizadas. Em vez de dizer apenas “coloque o objeto à esquerda”, você pode fornecer uma caixa e descrever o conteúdo associado a ela. A escala vai de 0 a 1000, portanto a descrição do layout não depende de a imagem final ter 1024 ou 2048 pixels de largura. Guia de caixas delimitadoras da BFL

Diagrama explicativo original. A caixa indica uma posição solicitada, não uma geração observada nem uma máscara rígida da imagem.

Veja este fragmento ilustrativo de legenda para geração. Ele descreve uma nova composição, não a edição de uma imagem de referência. Deve ficar dentro do prompt, não em um terminal:

A clean studio composition with a ceramic mug <mug_1> on the left.
[{"id":"mug_1","bbox":[200,80,850,480],"desc":"A plain ceramic mug with a visible handle"}]

A ordem é topo, esquerda, base, direita. Neste exemplo, a caixa começa a 20% da altura e 8% da largura da tela e termina a 85% da altura e 48% da largura. Para um projeto real, esboce primeiro a composição desejada e depois converta esse arranjo em coordenadas. Trocar os valores horizontal e vertical é uma maneira simples de obter um resultado confuso.

Uma edição precisa identificar tanto a origem quanto o destino. O corpo de API ilustrativo a seguir move uma caneca de uma caixa de origem central para uma caixa de destino à esquerda. Substitua a URL de exemplo por uma imagem acessível que seja sua; não envie o espaço reservado sem alterações. A primeira referência é ref_image_0.

{
  "images": ["https://example.com/your-own-mug.png"],
  "output_format": "png",
  "prompt": "In <ref_image_0>, move the mug <mug_1> to the left. Preserve the mug's handle and the plain background. [{\"id\":\"mug_1\",\"from\":\"ref_image_0\",\"src_bbox\":[200,300,850,700],\"tgt_bbox\":[200,80,850,480],\"desc\":\"The same plain ceramic mug with its handle visible\"}]"
}

Aqui, from nomeia a referência, src_bbox identifica a região original e tgt_bbox descreve o destino solicitado. Acrescente linhas para outros elementos quando precisar de um plano de preservação mais detalhado. O arquivo boxes.json da CLI local usa coordenadas de 0 a 1; não cole nele os valores de 0 a 1000 da API. Sintaxe de edição hospedada, formato local de caixas

Não trate uma caixa como garantia de que tudo fora dela ficará intacto. A documentação do checkpoint original alerta que as edições podem afetar outras regiões e que os elementos podem ultrapassar suas caixas. O caminho de edição hospedado da BFL também inclui um recurso de restauração de pixels; não atribua silenciosamente esse recurso de serviço a todo fluxo local. Verifique a implementação que está usando. Limitações do checkpoint

Para trabalhos de impressão ou de clientes, sobreponha a imagem antiga e a nova em um editor. Se o objeto foi movido com sucesso, mas o texto da embalagem mudou, a tarefa de composição foi bem-sucedida, enquanto a preservação do material falhou. São avaliações diferentes; separá-las torna a iteração bem menos frustrante.

Uma requisição à API inicia um trabalho, não entrega o arquivo final

Desenvolvedores podem enviar uma solicitação de imagem ao endpoint documentado. Em um terminal macOS ou Linux, defina BFL_API_KEY como variável de ambiente privada e use este exemplo curto. O serviço pode gerar cobranças; não coloque a chave em um repositório público nem em um pacote de navegador.

curl --fail-with-body --request POST \
  --url https://api.bfl.ai/v1/flux-3-image-klein \
  --header "x-key: $BFL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"prompt":"A simple studio photograph of a plain ceramic mug on a pale green surface","aspect_ratio":"16:9","output_format":"png"}' \
  --output bfl-job.json

No Windows PowerShell, use o mesmo endpoint com a serialização JSON nativa:

$body = @{
    prompt = "A simple studio photograph of a plain ceramic mug on a pale green surface"
    aspect_ratio = "16:9"
    output_format = "png"
} | ConvertTo-Json
$job = Invoke-RestMethod -Method Post `
    -Uri "https://api.bfl.ai/v1/flux-3-image-klein" `
    -Headers @{ "x-key" = $env:BFL_API_KEY } `
    -ContentType "application/json" -Body $body
$job | ConvertTo-Json -Depth 10 | Set-Content -Encoding utf8 bfl-job.json

Escolha um dos métodos de envio acima. Ambos salvam o trabalho aceito em bfl-job.json; nenhum deles baixa o resultado. Salve este script Python, que usa apenas a biblioteca padrão, como poll_result.py na mesma pasta. Mantenha BFL_API_KEY disponível para o processo e execute python poll_result.py no Windows ou python3 poll_result.py no macOS/Linux. Ele consulta o trabalho existente e salva result.png, sem enviar outra geração.

import json
import os
from pathlib import Path
import time
from urllib.parse import urlparse
from urllib.request import Request, urlopen

job = json.loads(Path("bfl-job.json").read_text(encoding="utf-8-sig"))
polling_url = job["polling_url"]
parsed = urlparse(polling_url)
if parsed.scheme != "https" or not (parsed.hostname or "").endswith(".bfl.ai"):
    raise ValueError("Unexpected polling host; inspect the saved job")
headers = {"x-key": os.environ["BFL_API_KEY"]}
deadline = time.monotonic() + 600

while time.monotonic() < deadline:
    with urlopen(Request(polling_url, headers=headers), timeout=60) as reply:
        result = json.load(reply)
    status = result["status"]
    print(job["id"], status)
    if status == "Ready":
        sample = result["result"]["sample"]
        if urlparse(sample).scheme != "https":
            raise ValueError("Unexpected result URL")
        with urlopen(sample, timeout=120) as image:
            Path("result.png").write_bytes(image.read())
        print("Saved result.png; inspect it before accepting the asset")
        break
    if status not in {"Pending", "Reasoning", "Generating"}:
        raise RuntimeError(f"Job stopped: {status}; keep bfl-job.json")
    time.sleep(1.5)
else:
    raise TimeoutError("Keep bfl-job.json and resume polling this job later")

A API de resultados distingue estados em execução, pronto, moderado e erro. Se uma exceção de rede interromper o script, mantenha o arquivo do trabalho e execute novamente o consultor de status, não o comando de envio. Examine uma resposta de envio incerta antes de tentar de novo: perder a resposta não prova que o serviço recusou o trabalho pago. Esquema da requisição

Um aplicativo útil mantém três registros: o material de origem, o trabalho de geração e o resultado aprovado. O usuário deve poder voltar ao original mesmo depois de rejeitar uma revisão. Esse projeto vale mais do que um botão que esconde todas as etapas intermediárias e produz um JPEG misterioso.

A instalação local começa pelo orçamento total de memória

O rótulo 5,6B do Klein se refere ao transformador de imagem, não a todos os componentes necessários ao fluxo de trabalho. O codificador de texto, o autoencoder de imagem, o expansor de prompt, as ativações e os tokens das imagens de referência também consomem recursos. A CLI de referência, a demonstração e a API Python ativam o expansor por padrão; a BFL instrui explicitamente a mantê-lo ativo, a menos que se forneça uma legenda já preparada no estilo do expansor. Portanto, o tamanho dos arquivos de pesos não é uma estimativa confiável da VRAM total. A mesma distinção importa ao avaliar grandes modelos de linguagem locais. Implementação de referência

A BFL anuncia caminhos otimizados para GPUs de consumo, inclusive uma configuração INT8 para uma placa de 8 GB. O cartão do modelo com código de referência relata picos consideravelmente maiores em outras configurações. Essas declarações descrevem receitas diferentes; nenhuma é um requisito mínimo universal para toda interface, resolução e quantidade de referências. Registre o runtime, a precisão, o tamanho da imagem e a política de offloading junto a cada valor de memória. Exemplos de hardware do lançamento, detalhes de hardware do código de referência

Lista de recursos original, não um benchmark. O tamanho dos componentes e os picos de execução variam conforme a receita.

No Windows com uma GPU NVIDIA compatível, comece pela integração atual do ComfyUI ou pelo runtime recomendado pela BFL. Confirme o fluxo específico do FLUX 3 em vez de carregar um modelo FLUX 2 cujo nome parece semelhante. Baixar o modelo com sucesso não comprova que nós personalizados, kernels quantizados e codificadores de texto sejam compatíveis.

No Linux, o repositório de referência e o guia de integração do Diffusers oferecem caminhos voltados a desenvolvedores. A instalação de referência abaixo segue a receita CUDA 13 documentada, testada pelo editor em uma B200; não é uma receita para placas de 8 GB. Para usar esses comandos Bash, quem está no Windows precisa de um ambiente Linux/WSL compatível. Confirme primeiro a compatibilidade do driver e o orçamento total de memória.

1. Instale Git e Python 3.12 e prepare um ambiente isolado:

git clone https://github.com/black-forest-labs/flux-3-image-klein.git
cd flux-3-image-klein
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e . --extra-index-url https://download.pytorch.org/whl/cu130

2. Aceite os termos do checkpoint na sua própria conta Hugging Face, autentique-se com hf auth login e baixe o pacote destilado documentado. O README de referência prevê cerca de 52 GB em disco para esse modelo, o expansor e o classificador de segurança; espaço em disco não é VRAM.

hf download black-forest-labs/flux-3-image-klein --local-dir weights/flux-3-image-klein --exclude 'variants/*'
hf download black-forest-labs/flux-3-image-klein-pup --local-dir weights/pup
hf download Falconsai/nsfw_image_detection --local-dir weights/nsfw-classifier

3. Execute uma geração mantendo ativo o expansor de prompt e depois inspecione out.png e o JSON de configurações que a acompanha:

python scripts/cli.py "A plain ceramic mug on a pale green studio surface" --model distilled --out out.png --seed 7

4. Para abrir no navegador uma interface que roda na sua máquina, execute python scripts/app.py, acesse http://127.0.0.1:7860, escolha Edit, anexe uma imagem de origem sua e indique uma alteração. Layout é a aba separada para desenhar caixas. Mantenha o aplicativo restrito ao loopback; não ative o compartilhamento público para material privado. Configuração e demonstração de referência

Adicione quantização ou offloading para CPU somente depois de obter uma configuração básica funcional. Para uma GPU de 8 GB, siga os arquivos e as instruções separados para ComfyUI, não as premissas de memória do código de referência completo.

Em um Mac, usar o navegador e a API continua sendo simples. Não copie os comandos de instalação CUDA nem os números de velocidade da NVIDIA como expectativa para um Apple Silicon. Um caminho local exige uma implementação compatível com Metal/MPS e memória unificada suficiente para todos os componentes; um exemplo genérico de biblioteca que usa mps não comprova que todos os caminhos quantizados funcionem. Macs Intel são um caso de hardware distinto, não outro nome para Apple Silicon.

Um prompt mais longo ajuda quando elimina ambiguidades

A implementação de referência expande uma instrução curta para uma legenda completa da cena antes de gerar a imagem. Esse upsampling de prompt é uma etapa separada de modelo de linguagem, ativada por padrão na CLI, na demonstração e na API Python de referência. O README atual também aponta para um pipeline Diffusers que faz essa expansão a cada solicitação. Preserve esse comportamento em vez de tratar um prompt curto e simples como equivalente. Preparação do prompt

Se o expansor e o modelo de imagem não couberem juntos, a receita de referência permite executar primeiro a expansão e passar a legenda preparada para a geração. Um modelo externo de visão e linguagem também pode prepará-la usando os prompts de sistema publicados. Somente essa legenda já preparada deve ser usada com --no-pup; a opção não é uma otimização de memória gratuita para uma solicitação de uma linha ainda não expandida. Upsampling e restauração de pixels hospedada são recursos diferentes; manter um não demonstra que outro runtime inclua o outro.

Antes de acrescentar sintaxe especializada, descreva o objeto, o fundo, a iluminação e a mudança desejada em linguagem comum. “Deixe profissional” deixa quase tudo em aberto. “Preserve a caneca e a alça, use um fundo simples e deixe livre o terço direito” oferece menos objetivos conflitantes ao sistema. Mais adjetivos não tornam automaticamente a instrução melhor.

Em um segundo uso, crie uma família de ilustrações para artigos. Mantenha constantes a paleta e a descrição do objeto enquanto muda a composição para um cabeçalho largo e uma imagem quadrada para redes sociais. Verifique a consistência do objeto entre formatos; não presuma que um resultado bem-sucedido em uma proporção se transfira perfeitamente para outra.

Em um terceiro uso, compare internamente maquetes de embalagens. Use rótulos fictícios ou material aprovado e identifique os resultados como conceitos. Uma imagem atraente não comprova viabilidade de fabricação, reprodução fiel das cores nem permissão para usar a imagem de uma pessoa fotografada. Uma análise de produção ainda será necessária depois da geração.

Calcule o custo do material final, não apenas de uma requisição bem-sucedida

O anúncio de lançamento informa preços de API a partir de US$ 0,009 por imagem de 1K, em 15 de outubro. Esse valor inicial não é uma promessa para toda resolução ou fluxo de trabalho. Consulte os preços atuais da BFL, as cobranças da conta e as regras das requisições antes de estimar uma campanha.

Para fazer o orçamento, conte as tentativas por material aprovado. Se uma tarefa exige cinco revisões, a unidade relevante inclui essas cinco tentativas, além do tempo de análise e finalização. A execução local substitui parte das cobranças do serviço por hardware, eletricidade, armazenamento e manutenção; não elimina o custo de inspecionar os resultados.

Pesos abertos tampouco significam direitos comerciais irrestritos. A FLUX Kommunity License diferencia uso não comercial, geração de resultados comerciais dentro dos critérios e outras atividades comerciais. Limites de receita, afiliadas, redistribuição do modelo e usos em treinamento exigem verificações próprias. Os direitos sobre uma foto de entrada, marca registrada ou pessoa são independentes da licença do modelo.

Quando uma edição dá errado, restrinja o diagnóstico

Perguntas para responder antes do segundo projeto

O FLUX 3 Image Klein substitui o Photoshop?

É um modelo de geração e edição com várias formas de execução, não um aplicativo completo de produção baseado em camadas. Ele pode ajudar a criar ou revisar materiais; ferramentas de seleção, tipografia precisa, gerenciamento de cores, controle de versões e entrega ainda podem pertencer ao seu editor.

Posso usar texto em coreano e esperar letras exatas?

Teste o texto real no tamanho de entrega. O cartão do modelo alerta que o texto renderizado pode ficar incorreto ou distorcido. Uma demonstração legível em inglês não comprova uma composição tipográfica confiável em coreano. Sempre que possível, mantenha o texto exato como elemento editável.

A inferência local mantém offline todas as etapas do fluxo?

Somente se você tiver configurado isso de propósito. Downloads iniciais, expansão remota de prompts, nós externos e telemetria podem gerar tráfego de rede. Inspecione o fluxo inteiro, não apenas onde fica o transformador de imagem.

Qual checkpoint um iniciante deve escolher?

Comece pelo caminho documentado de geração destilada. O checkpoint base é voltado à adaptação e à pesquisa. Depois de estabelecer uma tarefa que funciona, compare alternativas com as mesmas entradas, em vez de mudar simultaneamente modelo, prompt e resolução.

O avanço útil é uma revisão em que você pode confiar

Na nossa visão, a IA para imagens se torna mais útil quando dá às pessoas mais controle sobre as revisões, não apenas uma galeria maior de surpresas. O FLUX 3 Image Klein é interessante porque reúne referências, layouts e vários caminhos de implantação, aproximando esse controle do trabalho cotidiano. O próximo passo é deixar visíveis o original, a alteração solicitada e os critérios de aceitação.

Comece com uma imagem e uma edição deliberada. Um fluxo que produz de modo confiável um material aprovado é melhor do que um modelo rápido que deixa você tentando adivinhar o que mudou.

Fontes e mídia

Verificado em 18 de outubro de 2026. Os recursos do produto e os dados de desempenho acima vêm dos editores vinculados; não alegamos benchmark local nem geração paga. Os três diagramas são ilustrações explicativas originais. Consulte a galeria oficial de resultados da BFL e a demonstração interativa oficial para ver exemplos do produto; essas imagens de terceiros não são republicadas aqui.

• Anúncio da BFL, 15 de outubro
• Checkpoint, limitações e receitas locais
• Integração Diffusers e exemplos de fluxo, 15 de outubro
• Esquema de requisição da API BFL
• Licença FLUX Kommunity

Mantenha seus experimentos reutilizáveis

Guarde links das fontes, prompts, configurações e notas de revisão juntos, em vez de salvar apenas a imagem final. O Telli.sh pode ajudar a organizar essas notas de pesquisa; não é uma integração de geração de imagens. Crie uma conta no Telli.sh