Como usar a FLUX.3 Image API? Gere sua primeira imagem em 5 minutos

TL;DR

• A FLUX.3 Image é um modelo de imagem da Black Forest Labs lançado em outubro de 2026, com o nome de modelo flux-3-image. Um único nome de modelo cobre tanto geração a partir de texto quanto edição de imagem, e a edição aceita até 10 imagens de referência. Abra a página do modelo para testar online.
• Cobrança por imagem: 1K (padrão) $0.048, 2K $0.10, 4K $0.607, com 20% de desconto em todas as faixas até 31 de outubro. Cada tarefa gera 1 imagem.
• O caminho mais rápido: POST /v1/tasks com prompt, faça polling até success e baixe output[0].url. Lembre-se de escrever resolution explicitamente, e verifique tanto o status fail quanto failed.

O que é a FLUX.3 Image e o que há de novo?

• Geração e edição com um único nome de modelo. Sem passar image_urls, é geração a partir de texto; passando de 1 a 10 imagens de referência, a edição é feita em torno delas, e o prompt deve deixar claro o papel de cada imagem.
• Cinco faixas de resolução: de 768 ($0.041) a 4K ($0.607); 15 proporções de 21:9 a 9:21, além de auto.
• Busca na web para complementar detalhes. grounding vem ativado por padrão e, antes de gerar, pode pesquisar páginas e imagens na web para complementar informações da cena.
• 9º lugar no ranking de text-to-image da Artificial Analysis.

Imagem de interior em 1.5K, 3:2:

Architectural interior photograph of a cedar alpine reading cabin,
floor-to-ceiling window opening onto a misty mountain lake, linen armchair and a
small brass lamp, warm wood grain, quiet morning atmosphere, restrained
Scandinavian design, no text.

Gerar com este prompt → (1.5K, 3:2)

flux-3-image, 1.5K, 3:2, $0.07.

Duas rotas para começar

Teste online (sem escrever código):

1. Abra a página do modelo FLUX.3 Image e faça login (novos usuários ganham 200 créditos ao se registrar).
2. Cole o prompt, escolha a resolução e a proporção e, se precisar, envie imagens de referência.
3. Clique em gerar e baixe o resultado.

Chamada via API:

1. Crie uma API Key no console.
2. POST /v1/tasks, com "model": "flux-3-image".
3. Faça polling em GET /v1/tasks/{taskId} ou receba callback e salve output[0].url.

curl: gerando a primeira imagem

1K, 4:3, $0.048:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "input": {
      "prompt": "A refined still life of a terracotta architectural model on ivory paper, brass desk lamp, olive leaves, soft late-afternoon sunlight, no text",
      "resolution": "1K",
      "aspect_ratio": "4:3"
    }
  }'

A resposta traz data.taskId. Faça polling em GET /v1/tasks/{taskId} e, quando status mudar para success, baixe output[0].url.

Python: enviar, fazer polling e baixar

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": "flux-3-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A cinematic rainy Tokyo side street at blue hour, a small bookstore with warm amber windows, a red bicycle outside, no readable signs",
    resolution="2K", aspect_ratio="16:9",
)
ext = url.split("?")[0].rsplit(".", 1)[-1]  # 按返回的文件类型保存
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

Editar com imagens de referência

Passe image_urls (de 1 a 10 links públicos) e, no prompt, deixe claro o que cada imagem fornece e o que não deve ser trazido. A composição de três imagens abaixo: a imagem 1 fornece o objeto principal, a imagem 2 fornece a cena e a imagem 3 empresta apenas a paleta de cores.

Create a refined product photograph. Use the cobalt blue ceramic teapot and
walnut handle from Image 1 as the main subject, place it on a pale stone side
table inside the cedar reading cabin from Image 2. Borrow only the subtle teal
and amber lighting palette from Image 3. Preserve the teapot shape and glaze,
keep the lake window visible in the background, realistic scale, no lettering.

url = generate(
    prompt=open("teapot_prompt.txt").read(),
    image_urls=[
        "https://your-cdn.example.com/teapot.jpg",   # 图 1：主体
        "https://your-cdn.example.com/cabin.jpg",    # 图 2：场景
        "https://your-cdn.example.com/street.jpg",   # 图 3：只借配色
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image, três imagens de referência, 3:2, $0.048. As imagens de referência não têm custo extra.

Consulta rápida de parâmetros

Campo	Valores	Descrição
prompt	string, obrigatório, até 5000 caracteres	Descreva a cena, ou deixe claro o que alterar e o que preservar
image_urls	1–10 links públicos, opcional	Se não passar, é geração a partir de texto
resolution	768 / 1K / 1.5K / 2K / 4K, padrão 1K	Define o preço; a largura e a altura reais variam conforme a proporção
aspect_ratio	21:9 2:1 16:9 3:2 7:5 4:3 5:4 1:1 4:5 3:4 5:7 2:3 9:16 1:2 9:21 auto, padrão auto	Para posicionamentos fixos, escolha a proporção explicitamente
safety_tolerance	0–4, padrão 2	0 é o mais restritivo
grounding	booleano, padrão true	Pesquisa páginas e imagens na web antes de gerar

Cuidados antes de ir para produção

• Escreva resolution sempre. Um deslize ao digitar 4K faz uma imagem passar de $0.048 para $0.607.
• Verifique tanto fail quanto failed. A documentação diz failed, mas verificar os dois é mais seguro.
• Use callback em vez de polling: adicione "callback": {"url": "https://your-app.example.com/hiapi/callback"} no mesmo nível de input e deduplique por taskId.
• Salve o resultado imediatamente. output[0].url tem prazo de validade; baixe a tempo ou escolha armazenamento permanente ao criar a tarefa.
• Inclua o cabeçalho Idempotency-Key; ao repetir a tentativa, a mesma Key cria a tarefa apenas uma vez.

Perguntas frequentes

Quantas imagens cada tarefa gera?

1. Se quiser várias direções, envie tarefas separadas.

É possível escolher PNG ou JPEG?

Este modelo não oferece escolha de formato. Se precisar de um formato específico, converta após o download.

Quando desativar a busca na web?

Quando você já tem suas próprias imagens de referência e a direção criativa já está definida. Escreva grounding: false; o preço não muda.

Falhas na geração são cobradas?

Não. Só há cobrança quando a imagem é gerada com sucesso.

Veja os preços de cada faixa em Preços da FLUX.3 Image API, mais prompts em Exemplos de prompts da FLUX.3 Image, e a comparação com o mesmo prompt na geração anterior em FLUX.3 Image vs FLUX.2. Você também pode ir direto à página do modelo para gerar esta cabana de cedro.