FLUX 3 Image API: guia de 4K e múltiplas referências

A FLUX 3 Image já pode ser usada por meio de um modelo da Black Forest Labs hospedado no Replicate e de endpoints parceiros. Ela oferece saída em 4K e edição com até 10 imagens de referência. A documentação nativa da BFL, porém, ainda está concentrada na FLUX 3 Video, enquanto cada provedor de imagem adota seu próprio schema, limites e modelo de cobrança.

A FLUX 3 Image API está realmente disponível?

Sim, a FLUX 3 Image API está disponível — mas é importante definir exatamente o que “oficial” significa. A evidência mais forte é o modelo ativo black-forest-labs/flux-3-image, de propriedade da Black Forest Labs no Replicate. Ele aceita solicitações de geração, entra no modo de edição quando uma imagem é enviada e oferece 4k como opção de resolução.

O artigo de ajuda da BFL sobre a FLUX 3 descreve apenas o modelo de vídeo. Já a listagem separada da BFL no Replicate e os endpoints parceiros confirmam a disponibilidade da edição de imagens.

Antes de o endpoint aparecer, o usuário u/rerri, do Reddit, previu que o lançamento priorizaria a API:

“Eu não ficaria surpreso se a Flux 3 Image lançasse primeiro apenas como API.” — u/rerri no r/StableDiffusion

O lançamento seguiu essa previsão, mas ter acesso à API não significa que os pesos abertos estejam disponíveis.

O que a edição em 4K e com várias referências muda na prática

A FLUX 3 Image oferece saída em 4k e aceita até 10 imagens de referência. Nenhum desses recursos garante que o resultado manterá perfeitamente todas as identidades, detalhes de um produto ou pequenos trechos de texto. As páginas dos provedores mostram controles e exemplos, mas não apresentam avaliações independentes de qualidade.

O README do Replicate mantido pela BFL lista 768sq, 1k, 1.5k, 2k e 4k. Os arquivos de referência podem estar em JPEG, PNG, GIF ou WebP, precisam ter pelo menos 256 por 256 pixels e não podem ultrapassar 16 megapixels. Com aspect_ratio: auto, a primeira referência define a proporção da edição.

O schema de edição da fal é parecido, mas não idêntico. Ele aceita de 1 a 10 URLs ou data URIs, limita cada entrada a 4 megapixels, oferece opções de 512sq a 4k e avisa que o processamento em 4K pode levar vários minutos. A ordem das referências tem significado: “imagem 1” é o primeiro item de image_urls.

Em edições com várias referências, atribua uma função a cada entrada: composição-base, identidade do personagem, produto ou estilo. A própria fal recomenda fazer uma edição por solicitação. Um prompt como “Use a imagem 1 como base; substitua apenas a garrafa pelo produto da imagem 2; preserve o ângulo da câmera, as mãos, a iluminação e o fundo” é mais fácil de revisar do que uma solicitação que também altere roupa, tipografia e localização.

Um fluxo prático para APIs em fila

Em produção, trate a geração pela FLUX 3 Image API como um trabalho assíncrono. A aplicação deve enviar URLs estáveis para as entradas, fazer uma solicitação objetiva, armazenar o ID retornado pelo provedor, consultar o status com backoff e copiar o resultado concluído para seu próprio armazenamento.

O exemplo a seguir usa o identificador de endpoint e os campos documentados pela fal. Ele é um modelo de integração, não uma afirmação de que a solicitação foi executada durante esta análise.

import os
import time
import requests

ENDPOINT = "https://queue.fal.run/blackforestlabs/flux-3/edit-image"
headers = {
    "Authorization": f"Key {os.environ['FAL_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "prompt": (
        "Use image 1 as the base. Replace only its package with the product "
        "from image 2. Preserve the hands, camera angle, shadows, and background."
    ),
    "image_urls": [
        "https://cdn.example.com/base.jpg",
        "https://cdn.example.com/product.png",
    ],
    "resolution": "1k",
    "aspect_ratio": "auto",
    "output_format": "png",
    "safety_tolerance": 2,
}

submitted = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)
submitted.raise_for_status()
job = submitted.json()

status_url = job["status_url"]
response_url = job["response_url"]
while True:
    status = requests.get(status_url, headers=headers, timeout=30)
    status.raise_for_status()
    state = status.json().get("status")
    if state == "COMPLETED":
        break
    if state in {"FAILED", "CANCELLED"}:
        raise RuntimeError(status.text)
    time.sleep(2)

result = requests.get(response_url, headers=headers, timeout=30)
result.raise_for_status()
print(result.json())

A documentação da fila da fal vinculada na página do modelo também oferece sync_mode, mas a execução em fila é o padrão mais seguro para 4K, já que uma renderização pode ultrapassar o timeout normal de uma requisição HTTP. A Layer deixa esse contrato assíncrono explícito: o envio retorna HTTP 202, um inference_id e um intervalo de consulta recomendado. A Layer também oferece chaves de idempotência que podem ser reutilizadas por 24 horas, ajudando a evitar cobranças duplicadas após novas tentativas causadas por falhas de rede.

Antes de liberar tráfego:

1. Recuse imagens com menos de 256 pixels em qualquer lado e aplique o limite de megapixels do provedor selecionado.
2. Preserve a ordem do array e gere prompts que façam referência a image 1, image 2 e assim por diante.
3. Use uma chave de idempotência exclusiva quando o provedor oferecer esse recurso; caso contrário, persista a solicitação antes de tentar novamente.
4. Defina um limite para o tempo de consulta e mostre um estado pendente em vez de manter uma requisição da aplicação aberta.
5. Copie os arquivos concluídos para um armazenamento sob seu controle, pois as URLs hospedadas podem não seguir a política de retenção da aplicação.
6. Registre o ID do modelo, o provedor, a resolução, o número de referências, o custo informado, o tempo decorrido e o resultado da moderação em cada trabalho.

O verdadeiro equilíbrio entre custo e qualidade

A comparação de custos precisa ser limitada, porque os provedores não publicaram uma tabela completa por resolução nas páginas consultadas. A fal anunciava um preço promocional de US$ 0,024 por imagem em 1K, que subiria para US$ 0,048 após a promoção. A empresa também informava que a quantidade de referências não altera a cobrança. Os preços exatos para 2K e 4K não estavam publicados naquela página do modelo; portanto, não é possível deduzir um orçamento para 4K a partir do valor de 1K.

Em vez de presumir que 4K é sempre a melhor opção, adote uma política em duas etapas:

Uma resolução maior entrega mais pixels, não necessariamente uma edição mais fiel: um erro em 1K vira um erro maior em 4K. Reserve o 4K para edições aprovadas que serão usadas em impressão, outdoors ou recortes agressivos.

Na inicialização da aplicação, envie um trabalho de teste mínimo e válido ou consulte a superfície de preços do provedor, registre o valor informado e desative o 4K se a cotação estiver ausente ou ultrapassar o orçamento do trabalho. A resposta inicial da Layer pode incluir estimated_price_creative_units; sua página pública do modelo não informava a conversão para dólares. A página consultada do Replicate documentava as entradas, mas não apresentava um preço fixo. Essas são lacunas de contratação que precisam ser resolvidas no painel da conta antes do lançamento — não números para serem inventados no código.

Escolha o endpoint pelo encaixe operacional

A escolha do provedor deve partir do contrato de que sua aplicação precisa. O fato de dois modelos terem o mesmo proprietário não torna seus schemas intercambiáveis.

• Replicate: escolha a listagem mantida pela BFL quando a procedência for prioridade e sua stack já usar o fluxo de previsões do Replicate. Entre as opções analisadas, ela documenta o maior limite de entrada, de 16 MP, e inclui grounding opcional na web e em imagens.
• fal: escolha o endpoint parceiro de edição quando controles claros para edição, um fluxo em fila e um preço visível para 1K forem mais importantes. Seu limite de entrada de 4 MP exige uma redução de escala antecipada.
• Layer: escolha-a para organização em workspace, um contrato HTTP 202 formal, orientações de consulta e idempotência por 24 horas. Confirme como as Creative Units são convertidas em dólares antes de definir um orçamento.

Não identifique um provedor apenas pela presença de “FLUX3” no domínio ou no nome do repositório. Verifique o ID do modelo, o proprietário ou rótulo de parceiro, os valores atuais dos enums, os termos comerciais e uma solicitação de baixo custo concluída com sucesso. O wrapper Anil-matcha/Flux-3-Dev-API, que aparecia em posições altas nos resultados, ainda marcava suas rotas de imagem como “em breve” no momento da verificação, enquanto as rotas da BFL no Replicate e da fal estavam ativas.

Checklist para liberar em produção

A FLUX 3 Image é adequada para testes controlados via API, incluindo saída em 4K e até 10 referências. Só coloque o recurso em produção depois que o endpoint escolhido passar pelo mesmo conjunto representativo de edições em 1K e na resolução final.

A recomendação prática é começar pela edição em 1K, registrar dados de preço e latência e habilitar 2K ou 4K apenas para arquivos finais aprovados. Assim, os recursos mais fortes e documentados do novo modelo ficam disponíveis sem criar uma suposição não verificada sobre qualidade ou custo em alta resolução.

Leituras relacionadas

• Visão geral do produto FLUX 3
• Comparativo das APIs de geração de imagens mais baratas