Como usar a API de text-to-image do FLUX.2? Parâmetros, código e uma imagem real gerada

TL;DR

• O text-to-image do FLUX.2 Pro tem o nome de modelo flux-2/text-to-image na HiAPI, é da Black Forest Labs, e tem como pontos fortes a aderência ao prompt e o texto dentro da imagem. Abra a página do modelo para testar online.
• Cobrança por faixa de resolução: 0.5 MP $0.0375, 1 MP (padrão) $0.05, 2 MP $0.075, 4 MP $0.125. A proporção não afeta o preço.
• O jeito mais rápido: POST /v1/tasks passando prompt, fazer polling até success e baixar output[0].url. O valor de resolution tem um espaço no meio, deve ser escrito como "1 MP".

Primeiro, veja uma imagem real gerada

A imagem abaixo foi gerada com a requisição deste artigo, 2 MP, 16:9:

A wide overhead flat-lay of a modern developer desk: a matte black mechanical
keyboard on the left, a ceramic mug of steaming coffee on the right, a small
potted succulent in the top corner, and an open spiral notebook in the center
with the handwritten words 'API ready' clearly visible on the page, soft
natural window light falling from the left, a muted teal and warm wood color
palette, no other text or logos anywhere in the frame

Gerar com este prompt → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0.075. O «API ready» no caderno saiu correto e não há texto sobrando na imagem.

Consulta rápida de parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	string	Coloque os elementos importantes no início da frase; 30–80 palavras em inglês funcionam melhor
aspect_ratio	Não	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, padrão 1:1	Ao escolher custom, use junto com width / height
resolution	Não	0.5 MP / 1 MP / 2 MP / 4 MP, padrão 1 MP	Define o preço; ignorado quando custom
width / height	Apenas custom	256–2048	Arredondado automaticamente para múltiplo de 16
output_format	Não	webp (padrão) / jpg / png
output_quality	Não	0–100, padrão 80	Só se aplica a webp e jpg
seed	Não	inteiro	Fixado, permite reproduzir o mesmo resultado
safety_tolerance	Não	1–5, padrão 2	1 é o mais rigoroso

Os parâmetros são validados estritamente: se você enviar um campo a mais que não está na documentação, a API retorna diretamente HTTP 400 (additional properties ... not allowed). Este endpoint só aceita texto; para editar imagens com imagem de referência, use flux-2/image-to-image.

curl: gere a primeira imagem

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A matte charcoal coffee bag on a rustic oak counter, kraft paper label reading DAYBREAK ROAST, warm morning window light",
      "aspect_ratio": "4:3",
      "resolution": "1 MP",
      "output_format": "png"
    }
  }'

A resposta traz apenas data.taskId, a imagem ainda não foi gerada. Faça polling em GET /v1/tasks/{taskId} e, quando status virar success, baixe a partir de 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-2/text-to-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 wide overhead flat-lay of a modern developer desk, an open notebook with the handwritten words 'API ready', soft window light",
    aspect_ratio="16:9", resolution="2 MP", output_format="png", seed=42,
)
with open("desk.png", "wb") as f:
    f.write(requests.get(url).content)

Quanto custa

Resolução	Por imagem	100 imagens
0.5 MP	$0.0375	$3.75
1 MP (padrão)	$0.05	$5.00
2 MP	$0.075	$7.50
4 MP	$0.125	$12.50

Preço atual da HiAPI, verificado em 18 de outubro de 2026.

Proporção, seed e formato de saída não afetam o preço; só a faixa de resolução conta. Falhas não são cobradas. Para gastar menos, o FLUX.2 [klein] 4B 1 MP custa $0.00143 por imagem; veja a comparação de todas as faixas em Preços da API FLUX.2.

Cuidados antes de ir para produção

• resolution tem um espaço no meio: escreva "1 MP", não "1MP" nem "1K"; se errar, retorna 400 e lista os valores aceitos.
• Tamanho custom ignora resolution: quando aspect_ratio for custom, a imagem é gerada conforme width × height.
• Para reproduzir, fixe o seed: mesmo prompt e mesmo seed geram resultados bastante consistentes, o que ajuda a comparar ao ajustar o texto.
• Salve o resultado imediatamente: output[0].url tem validade; baixe e guarde no seu próprio armazenamento.
• Use callback em vez de polling: adicione no mesmo nível de input o campo "callback": {"url": "https://your-app.example.com/hiapi/callback"} e deduplique pelo taskId.

Perguntas frequentes

resolution é obrigatório?

Não, o padrão é 1 MP. Mas recomenda-se sempre informar, para não confundir com 4 MP.

Dá para enviar imagem de referência?

Este endpoint não. Para editar imagens com referência ou compor várias imagens, use flux-2/image-to-image, com até 8 imagens de referência; veja prompts prontos em Prompts de edição de imagem do FLUX.2.

Por que retorna «additional properties not allowed»?

Você enviou um campo que este modelo não tem, como strength ou prompt_upsampling. Use apenas os campos da tabela de parâmetros acima.

Como escolher entre ele e o FLUX.3 Image?

O FLUX.3 Image usa um único nome de modelo para gerar e editar imagens, gera até 4K e aceita até 10 imagens de referência; o FLUX.2 Pro tem seed e largura/altura personalizadas, e 4 MP custa só $0.125. Veja a comparação com o mesmo prompt em FLUX.3 Image vs FLUX.2.

Copie o prompt da mesa acima e gere sua primeira imagem na página do modelo.