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

O FLUX 3 Image permite indicar onde devem ficar os elementos individuais, utilizando retângulos como parte do prompt de imagem. O mesmo sistema aceita edições numa imagem de referência: cada elemento pode ter uma posição de origem, um destino e uma descrição da alteração pretendida. 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 é entre planear uma composição completa e alterar um elemento numa imagem existente. Este guia explica como escolher entre as opções, converter um retângulo nas coordenadas necessárias e obter o resultado da API. É um guia exclusivamente baseado na documentação, consultada a 3 de outubro de 2026. A BIG CHANGE não gerou nem editou uma imagem com o produto.

A grande mudança

• O que mudou: O lançamento da BFL de 1 de outubro documenta a composição e edição através do v1/flux-3-image. A descrição da cena e a tabela de elementos em JSON partilham um prompt, e as caixas especificam posições ou edições. notas de lançamento da BFL
• Por que isso importa: Os criadores podem converter um retângulo planeado em coordenadas e, em seguida, especificar que elementos da imagem de referência devem ser mantidos, movidos ou substituídos. A decisão prática consiste em determinar o grau de especificação: a composição completa, uma instrução simples ou uma tabela de edição explícita. tutorial de caixas da BFL
• O que observar: Defina a resolução e o orçamento antes de enviar o pedido: os preços indicados para 1k e 4k são 0,048 e 0,607 dólares por imagem. Inspecione o resultado completo, porque os elementos podem ultrapassar os limites das caixas e uma edição pode afetar a iluminação, as sombras ou os reflexos nas áreas próximas. 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 utilização sem código. Utilize a via do navegador se quiser desenhar as regiões diretamente; utilize a API se precisar de fornecer coordenadas num pedido e obter o resultado por programação. Não examinámos os controlos atuais do Playground; por isso, as instruções abaixo explicam o formato documentado dos pedidos, não uma sequência de botões no navegador.

para utilizar a API, crie uma conta BFL, adicione créditos e obtenha uma chave no painel. Envie um JSON com um pedido 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 separados: estas instruções dizem respeito ao endpoint Image alojado pela BFL. A página do produto Image oferece uma licença comercial dos pesos através da equipa de vendas. As fontes consultadas para este guia não confirmam que os pesos do FLUX 3 Image estejam disponíveis para transferência em regime aberto. acesso ao FLUX 3 Image

Decida quanto da imagem pretende especificar

A BFL afirma que uma instrução simples de edição pode receber automaticamente uma caixa durante a expansão do prompt. Para controlar explicitamente o resultado, forneça a sua própria tabela. Nas instruções comuns, «image 1» significa a primeira imagem de 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, numa cadeia de caracteres ou numa lista. Quando fornecidas, podem ser de 1 a 10 imagens, cada uma entre 256 × 256 píxeis e 16 megapíxeis. O valor predefinido de aspect_ratio é auto: acompanha a primeira imagem de referência ou produz uma imagem quadrada quando não é fornecida nenhuma referência. Defina-o explicitamente se o layout exigir uma forma específica. visão geral do endpoint da BFL

Converta um retângulo numa caixa

Cada caixa é [top, left, bottom, right], com coordenadas inteiras de 0 a 1000. Primeiro são indicadas as coordenadas verticais. Cada eixo abrange a imagem inteira de forma independente, pelo que a grelha se adapta a um canvas horizontal ou vertical. formato de caixa da BFL

Para converter posições em píxeis, divida os valores superior e inferior pela altura da imagem e os valores esquerdo e direito pela largura. Multiplique cada resultado por 1000 e arredonde. A conversão documentada pela BFL utiliza um canvas de 1920 × 1080:

Portanto, a caixa é [100, 200, 900, 800]. O intervalo vertical vai de 10% a 90% da imagem; o intervalo horizontal, de 20% a 80%. Este cálculo explica por que motivo trocar a largura e a altura, ou indicar a esquerda antes do topo, altera a região pretendida. Mantenha a proporção utilizada para conceber 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 a correr, tem um fundo que cobre o canvas e uma figura dentro da caixa central. Este pedido abreviado segue o layout do exemplo; a BIG CHANGE não o executou:

{
  "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"
}

Num layout com texto, coloque cada linha numa linha própria da tabela e introduza as palavras exatas pretendidas em desc. As caixas orientam a posição e a escala; a BFL alerta que um elemento pode ultrapassar o respetivo retângulo. Não são máscaras rígidas de recorte. 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 as adições e remoções em ambos os locais. Acrescente linhas «keep» para os elementos que têm de permanecer na posição atual. O guia da BFL indica que os píxeis fora das caixas geralmente não mudam, mas a iluminação, os reflexos e as sombras nas áreas próximas podem ser afetados. Compare o resultado completo com a imagem de origem antes de aceitar a edição. A BFL também refere que, nos seus próprios testes, novos elementos em caixas de cerca de 40 × 25 píxeis muitas vezes não apareceram; esta é uma observação do fornecedor, não um limite 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 indicados pela BFL, consultados a 3 de outubro. A coluna de dez pedidos é um cálculo, não uma medição de despesas. A BFL indica o mesmo preço para a API e o Playground, com um crédito equivalente a 0,01 dólares. A resposta ao pedido inclui cost. Um pedido 4k custa cerca de 12,6 vezes o valor informado para 1k; escolha a resolução de saída exigida pela tarefa e reserve orçamento para tentativas adicionais. Alterar a resolução exige um novo pedido, e este guia não demonstra que dois pedidos produzam a mesma composição. preços da BFL

A configuração opcional grounding tem como padrão true, que ativa a pesquisa na Web e de imagens antes da geração. Segundo a BFL, desativá-la permite obter resultados mais rapidamente utilizando apenas o prompt. Não medimos essa diferença de velocidade nem verificámos a exatidão dos resultados fundamentados. documentação de fundamentação da BFL

Envie o pedido, consulte o estado e guarde o resultado

Depois do envio, guarde o polling_url devolvido e consulte exatamente esse URL com a sua chave da API. O URL indica a região que contém a tarefa. Pending, Reasoning e Generating indicam que a tarefa ainda está em andamento. Quando estiver em Ready, descarregue 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 falhada exige uma resposta diferente da de uma tarefa ainda em execução. Request Moderated indica que a entrada foi bloqueada; Content Moderated indica que o resultado foi bloqueado. Ajuste a entrada antes de tentar novamente. Para Error, inspecione a resposta; uma tarefa desconhecida ou expirada devolve Task not found. A BFL alerta que uma tarefa com falha pode retornar HTTP 503 com um corpo JSON normal, pelo que deve ler o respetivo status antes de tentar novamente. Imagens de referência demasiado grandes geram 400; um campo desconhecido, um valor inválido, um prompt vazio ou uma imagem demasiado pequena podem gerar 422. Campos como seed, width e input_image de outros endpoints não são aceites aqui. guia de geração e erros da BFL

A tentativa só fica concluída depois de guardar o resultado e inspecionar a posição dos elementos, o texto pedido e as áreas em redor da edição. Uma resposta Ready confirma que há um resultado disponível; a inspeção visual é que determina se corresponde ao pedido.

Fontes e leituras adicionais

• 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: registam a data do lançamento do modelo de imagem e descrevem o endpoint partilhado. As afirmações amplas sobre os controlos são analisadas em conjunto 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 píxeis 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: indica as tarifas utilizadas nos nossos cálculos. Volte a confirmar os preços e os parâmetros do pedido antes de pagar por uma tentativa; estes documentos são atualizados.