FLUX 3 Image: guia sobre caixas de layout e edições pontuais

O FLUX 3 Image permite descrever onde cada elemento deve aparecer usando retângulos como parte do prompt de imagem. O mesmo sistema aceita edições em uma imagem de referência: cada elemento pode ter uma posição de origem, um destino e uma descrição do que deve mudar. A Black Forest Labs adicionou o endpoint de imagem às suas notas de lançamento de 1º de outubro de 2026.

Para designers e criadores, a distinção útil está entre planejar toda a composição e alterar um elemento de uma imagem existente. Este guia explica como escolher entre essas opções, converter um retângulo nas coordenadas exigidas e recuperar o resultado da API. É um guia baseado apenas na documentação, verificada em 3 de outubro de 2026. A BIG CHANGE não gerou nem editou imagens com o produto.

A grande mudança

• O que mudou: O lançamento da BFL de 1º de outubro documenta composição e edição pelo v1/flux-3-image. A descrição da cena e a tabela JSON de elementos compartilham um prompt, com caixas que especificam posições ou edições. notas de lançamento da BFL
• Por que isso importa: Quem cria imagens pode converter um retângulo planejado em coordenadas e especificar quais elementos da referência devem ser mantidos, movidos ou substituídos. A escolha prática é quanto definir: a composição inteira, uma instrução simples ou uma tabela explícita de edição. tutorial de caixas da BFL
• O que observar: Escolha uma resolução e defina o orçamento antes de enviar a solicitação: os preços divulgados para 1k e 4k são US$ 0,048 e US$ 0,607 por imagem. Inspecione o resultado completo, pois os elementos podem ultrapassar os limites das caixas, e uma edição pode afetar a iluminação, as sombras ou os reflexos ao redor. preços da BFL, limites de edição

Escolha entre o navegador e a API

A página de produto da BFL descreve duas formas de acesso: desenhar caixas no Playground pelo navegador ou enviar um prompt de layout pela API. A documentação inclui um link para o Playground para uso sem código. Escolha o navegador se quiser desenhar as regiões diretamente; use a API se precisar enviar coordenadas em uma solicitação e recuperar a saída de forma programática. Não inspecionamos os controles atuais do Playground, portanto as instruções abaixo explicam o formato de solicitação documentado, não uma sequência de botões do navegador.

Para usar a API, crie uma conta BFL, adicione créditos e obtenha uma chave no painel. Envie um JSON com uma solicitação POST para https://api.bfl.ai/v1/flux-3-image, usando Content-Type: application/json e a chave no x-key cabeçalho. Apenas prompt é obrigatório. guia de geração da BFL, preços e configuração

Mantenha FLUX 3 Image e FLUX 3 Dev bem diferenciados: estas instruções tratam do endpoint Image hospedado pela BFL. A página do produto Image oferece uma licença comercial dos pesos mediante contato com a equipe de vendas. As fontes consultadas para este guia não confirmam a disponibilidade de um download dos pesos abertos do FLUX 3 Image. acesso ao FLUX 3 Image

Decida quanto da imagem especificar

A BFL diz que, durante a expansão do prompt, um comando simples de edição pode receber uma caixa automaticamente. Para ter controle explícito, forneça sua própria tabela. Em instruções comuns, “imagem 1” significa a primeira referência; nas linhas de edição, essa mesma referência é ref_image_0. guia de edição da BFL

As referências devem ser incluídas em images como URLs ou dados em base64, em uma string ou em uma lista. Quando fornecidas, podem ser de 1 a 10, cada uma com tamanho entre 256 × 256 pixels e 16 megapixels. O valor padrão de aspect_ratio é auto: ele acompanha a primeira referência ou produz um quadrado quando nenhuma é fornecida. Defina-o explicitamente se o layout exigir um formato específico. visão geral do endpoint da BFL

Converta um retângulo em uma caixa

Cada caixa é [top, left, bottom, right], com coordenadas inteiras de 0 a 1000. Primeiro vêm as coordenadas verticais. Cada eixo cobre a imagem inteira de forma independente, então a grade se ajusta a uma tela horizontal ou vertical. formato de caixa da BFL

Para converter posições em pixels, divida as coordenadas superior e inferior pela altura da imagem e as coordenadas esquerda e direita pela largura. Multiplique cada resultado por 1000 e arredonde. A conversão documentada pela BFL usa uma tela de 1920 × 1080:

Portanto, a caixa é [100, 200, 900, 800]. Sua extensão vertical vai de 10% a 90% do quadro; a horizontal, de 20% a 80%. Esse cálculo explica por que trocar largura por altura ou informar a esquerda antes do topo altera a região pretendida. Mantenha a proporção usada para criar o layout. conversão de coordenadas da BFL

Componha uma nova imagem

Descreva a composição inteira, nomeando os elementos com <id> como marcadores. Acrescente um array JSON com o campo id, bbox e desc para cada elemento. O array é texto dentro de prompt, não outro campo de nível superior da API.

O exemplo documentado pela BFL com a silhueta de uma pessoa correndo tem um fundo que cobre a tela e uma figura dentro da caixa central. Esta solicitação resumida segue o layout do exemplo; ela não foi executada pela BIG CHANGE:

{
  "prompt": "A black running silhouette <silhouette_1> on a chartreuse background <background_1>. [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"Chartreuse background with paper texture\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"Black running silhouette with stippled texture\"}]",
  "aspect_ratio": "1:1",
  "resolution": "1k"
}

Em um layout que contenha texto, coloque cada linha em sua própria linha da tabela e insira as palavras exatas solicitadas em desc. As caixas orientam o posicionamento e a escala; a BFL alerta que um elemento pode ultrapassar o retângulo. Elas não funcionam como máscaras de recorte rígidas. tutorial de composição e limites da BFL

Edite uma imagem existente

Forneça a imagem de origem em images. As linhas de edição mantêm id e desc, mas substituem bbox por estes campos:

Junte a instrução e o array de edição em prompt, como na composição. Descreva adições e remoções nos dois lugares. Inclua linhas de manutenção para os elementos que devem permanecer onde estão. O guia da BFL diz que os pixels fora das caixas geralmente permanecem iguais, mas a iluminação, os reflexos e as sombras ao redor podem mudar. Compare toda a saída com a imagem de origem antes de aceitar uma edição. A BFL também relata que, em seus próprios testes, novos elementos em caixas de cerca de 40 × 25 pixels muitas vezes não apareceram; essa é uma observação do fornecedor, não um mínimo universal nem um teste da BIG CHANGE. orientações de edição da BFL, esquema das linhas de edição

Escolha a resolução e defina o orçamento

A visão geral lista 768sq, 1k, 1.5k, 2k e 4k, sendo 1k o padrão. A página de preços publica as tarifas a seguir; ela não informa o preço da opção 1.5k. Confira o custo dessa opção antes de usá-la. visão geral da BFL

Estes são os preços em dólares americanos divulgados pela BFL, consultados em 3 de outubro. A coluna de dez solicitações é um cálculo, não uma medição de gastos. A BFL informa o mesmo preço para a API e o Playground, com um crédito equivalente a US$ 0,01. A resposta da solicitação inclui cost. Uma solicitação de 4k custa cerca de 12,6 vezes o valor informado para 1k; escolha o tamanho de saída exigido pela tarefa e reserve orçamento para tentativas adicionais. Alterar a resolução exige uma nova solicitação, e este guia não demonstra que duas solicitações produzam a mesma composição. preços da BFL

A configuração opcional grounding tem como padrão true, ativando a busca na web e por imagens antes da geração. Segundo a BFL, desativá-la acelera os resultados usando somente o prompt. Não medimos essa diferença de velocidade nem verificamos a precisão das respostas fundamentadas. documentação de fundamentação da BFL

Envie a solicitação, consulte o status e salve a saída

Depois do envio, guarde o polling_url retornado e consulte exatamente essa URL com sua chave de API. Ela aponta para a região que mantém a tarefa. Pending, Reasoning e Generating indicam que a tarefa ainda está em andamento. Quando estiver em Ready, baixe result.sample; o link assinado expira após uma hora. Não envie o cabeçalho x-key para a URL de download. O resultado também contém result.prompt, que mostra a instrução expandida, e result.duration, o tempo de geração. instruções de recuperação da BFL

Uma tarefa bloqueada ou com falha exige uma resposta diferente daquela de uma tarefa ainda em execução. Request Moderated indica que a entrada foi bloqueada; Content Moderated indica que a saída foi bloqueada. Ajuste a entrada antes de tentar novamente. Para Error, inspecione a resposta; uma tarefa desconhecida ou expirada retorna Task not found. A BFL alerta que uma tarefa com falha pode retornar HTTP 503 com um corpo JSON normal; portanto, leia seu status antes de tentar novamente. Referências grandes demais geram 400; um campo desconhecido, um valor inválido, um prompt vazio ou uma imagem pequena demais pode gerar 422. Campos como seed, width e input_image de outros endpoints não são aceitos aqui. guia de geração e erros da BFL

A tentativa só termina depois que você salva a saída e inspeciona o posicionamento, o texto solicitado e as áreas ao redor de uma edição. Uma resposta Ready confirma que há um resultado disponível; é a sua inspeção visual que determina se ele atende à tarefa.

Fontes e leituras complementares

• Página do produto FLUX 3 Image: confirma as opções de acesso pelo navegador e pela API, além do acesso comercial aos pesos. As demonstrações são materiais do fornecedor, não resultados de nossos testes.
• Notas de lançamento de 1º de outubro: registram a data do lançamento do modelo de imagem e descrevem o endpoint compartilhado. As afirmações amplas sobre controles são analisadas junto com os limites mais específicos dos tutoriais.
• Visão geral do endpoint: fornece parâmetros, limites das referências, opções de resolução e comportamento da fundamentação.
• Tutorial de caixas delimitadoras: explica os dois esquemas de linhas e o exemplo da silhueta em movimento adaptado acima.
• Guia de edição: dá suporte à conversão de coordenadas, à ordem das referências e às ressalvas sobre regiões pequenas e pixels ao redor.
• Guia de geração: documenta a autenticação, a recuperação assíncrona, os links com prazo de validade e os erros.
• Preços: fornece as tarifas usadas em nossos cálculos. Verifique os preços e parâmetros da solicitação antes de pagar por uma tentativa; estes são documentos atualizados.