Como usar a API do FLUX.1 Kontext Max? Gere sua primeira imagem em 5 minutos

TL;DR

• O que é: o FLUX.1 Kontext Max, criado pela Black Forest Labs, em que geração de texto para imagem e edição de imagem única compartilham o mesmo ID de modelo. Já está disponível na HiAPI: abra a página do modelo, insira um prompt e gere; novos usuários ganham 200 créditos ao se cadastrar, o equivalente a cerca de 1,4 imagem.
• Quanto custa: $0,0715 por imagem (143 créditos), mesmo preço para geração e edição; com $10 dá para gerar cerca de 139 imagens; tarefas com falha têm a cobrança prévia estornada.
• Como chamar a API: POST https://api.hiapi.ai/v1/tasks, escreva flux-1-kontext-max em model; após obter o taskId, faça polling ou aguarde o callback e baixe o resultado em data.output[0].url.

Desde o lançamento do FLUX.1 Kontext Max, duas perguntas são frequentes: é possível editar apenas um ponto da imagem e quanto tempo leva para integrá-lo ao próprio produto. Primeiro veja as capacidades, depois siga as duas rotas de início.

O que é o FLUX.1 Kontext Max e o que ele traz de novo?

• Um único ID de modelo atende dois tipos de tarefa. Se não enviar imagem em input, é geração de texto para imagem; se enviar input_image, é edição. O código não precisa de duas versões.
• A edição segue o princípio de "o que mudar, o que manter". É possível alterar materiais e estilos, adicionar ou remover elementos, ajustar cores e iluminação e modificar textos na imagem; o que não for mencionado no prompt é mantido o mais fiel possível ao original.
• Seis proporções de tela; na edição, é possível manter a proporção da imagem original. Em aspect_ratio, é possível escolher 21:9, 16:9, 4:3, 1:1, 3:4, 9:16; na edição, se deixar em branco, a saída mantém a proporção da imagem original, com pixels ajustados para múltiplos de 32; 1280×720 vira 1328×752.
• Saída em jpeg ou png, com cerca de 1 milhão de pixels por imagem. O limite de prompt é de 4.000 caracteres; prompts em chinês são automaticamente traduzidos para inglês antes da geração.

Geração de texto para imagem, 16:9. O prompt completo é o mesmo do curl abaixo e pode ser copiado como está.

Gerar com este prompt →

Duas rotas de início: teste online ou API?

Para ver o resultado, use o teste online; para integrar ao produto, use a API. As duas rotas usam o mesmo modelo e a mesma tabela de preços.

Teste online (cerca de 1 minuto)

1. Abra a página do modelo FLUX.1 Kontext Max ou clique no link abaixo da imagem acima; o prompt é preenchido automaticamente.
2. Cadastre-se ou faça login; novas contas já vêm com 200 créditos.
3. Escolha 16:9 e clique em gerar.
4. Se gostar, baixe; se quiser editar, envie a imagem original na mesma página e escreva o prompt de edição.

Integração via API (cerca de 5 minutos)

1. Crie uma API Key (sk-...) no console da HiAPI.
2. Use POST /v1/tasks para criar a tarefa e obtenha data.taskId na resposta.
3. Consulte com GET /v1/tasks/{taskId} ou aguarde a notificação de callback.url; quando data.status passar a success, baixe a imagem em data.output[0].url.

$0,0715 por imagem; com $10 dá para gerar cerca de 139 imagens, o suficiente para ajustar o prompt até ficar satisfeito. Os parâmetros completos estão na documentação em chinês.

Primeira imagem: versão curl

Criar a tarefa:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
      "aspect_ratio": "16:9",
      "output_format": "jpeg",
      "prompt_upsampling": false
    }
  }'

O ID da tarefa retornado fica em data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Consultar o resultado:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Apenas prompt é obrigatório. output_format é jpeg por padrão, prompt_upsampling vem desativado por padrão e safety_tolerance é 2 por padrão (0 é o mais rigoroso).

Primeira imagem: versão Python

Criação, polling e download em um único código; basta trocar pela sua própria Key para executar:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
        "aspect_ratio": "16:9",
    },
}

task_id = requests.post(API, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    image_url = data["output"][0]["url"]
    with open("flux-1-kontext-max.jpg", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(data.get("error"))

Modo de edição: basta adicionar um input_image

Adicione input_image em input e a mesma requisição passa de geração de texto para imagem a edição. Abaixo, use a imagem do canto de leitura acima como original, trocando apenas a poltrona e adicionando um abajur de piso:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "Change the linen armchair to a deep forest-green velvet armchair, add a slim brass floor lamp beside it, and keep the window, books, cup, table and afternoon light unchanged.",
      "input_image": "https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg"
    }
  }'

input_image aceita uma URL de imagem acessível publicamente. Na edição, se não escrever aspect_ratio, a saída mantém a proporção da imagem original; para combinar várias imagens, escolha a edição de imagem do GPT Image 2, que aceita de 1 a 16 imagens de referência.

Como escrever o prompt de edição: primeiro diga o que mudar, depois liste o que manter

1. Escreva a alteração como uma instrução clara. Detalhe o objeto e o novo estado: troque linen armchair por deep forest-green velvet armchair.
2. Nomeie cada item a manter. Janela, livros, xícara, mesa, luz da tarde — escreva tudo o que importa na imagem original e finalize com keep ... unchanged.
3. Alterações relacionadas podem ficar na mesma frase. Trocar a poltrona e adicionar um abajur de piso de latão ao mesmo tempo faz o modelo tratar tudo junto; modificações não relacionadas devem ser enviadas separadamente para facilitar a conferência do resultado.
4. Ao alterar textos na imagem, preserve também o layout. Por exemplo, para mudar KYOTO por OSAKA em um pôster, especifique ao mesmo tempo que o layout, os espaços em branco e o estilo da fonte permanecem como estão.
5. Pode escrever em chinês. O sistema traduz para inglês antes de gerar; mantenha o prompt dentro de 4.000 caracteres.

4 pontos de atenção antes de ir para produção

1. Use callback no servidor. Adicione "callback": {"url": "https://yourapp.com/webhook", "when": "final"} ao corpo da requisição para ser notificado automaticamente quando a tarefa chegar ao estado final, eliminando o polling.
2. Em caso de timeout, não repita o POST. Cada criação gera uma nova tarefa e cobra separadamente; salve primeiro o taskId e faça deduplicação no próprio sistema antes de tentar novamente.
3. Os links dos resultados expiram. data.output[0].url é um link temporário; baixe assim que receber e transfira para o seu próprio armazenamento.
4. Os pixels são alinhados a múltiplos de 32. Na edição, deixe aspect_ratio em branco: a proporção da imagem original é mantida e os pixels são ajustados para múltiplos de 32; 1280×720 gera 1328×752. Se especificar uma proporção, a imagem é cortada ou recebe bordas conforme essa proporção.

Perguntas frequentes

É preciso trocar de modelo entre geração e edição? Não. É o mesmo flux-1-kontext-max; enviar ou não input_image define qual caminho será usado, e o preço é o mesmo.

Quantas imagens de referência podem ser enviadas por vez? Uma. Para combinar várias imagens, escolha a edição de imagem do GPT Image 2, que aceita de 1 a 16 imagens de referência.

Posso usar prompts em chinês? Sim. O limite do prompt é de 4.000 caracteres; o chinês é traduzido automaticamente para inglês antes da geração.

A proporção da imagem muda após a edição? Se não escrever aspect_ratio, a proporção da imagem original é mantida e os pixels são ajustados para múltiplos de 32; se escrever, a imagem é cortada ou recebe bordas conforme a proporção especificada.

Tarefas com falha são cobradas? A cobrança é feita pela quantidade de imagens geradas com sucesso; cada requisição retorna 1 imagem, e tarefas com falha têm a cobrança prévia estornada.

Copie o prompt do canto de leitura acima para a página do modelo FLUX.1 Kontext Max, selecione 16:9, clique uma vez em gerar e veja primeiro como ele trata a luz e os materiais; depois decida se vale integrá-lo ao seu projeto.