Como usar a API do Imagen 4? Gere sua primeira imagem em 5 minutos

TL;DR

• O Imagen 4 (imagen-4.0) é um modelo de texto para imagem, a $0.06 por imagem: escreva um prompt e escolha a proporção para gerar a imagem, ideal para fotografia de retrato, close-ups da natureza e naturezas-mortas de produto. Abra a página do modelo para testar online; novos usuários ganham 200 créditos ao se cadastrar.
• A mesma família tem mais duas versões: imagen-4.0-fast a $0.03 por imagem para muitos testes de esboço, e imagen-4.0-ultra a $0.09 por imagem para detalhes de imagem final.
• A chamada usa a interface /v1/tasks do HiAPI: envie a tarefa e receba o taskId, depois consulte o resultado e, em caso de sucesso, baixe a imagem de output[0].url.

O que ele faz

• Imagem direto do texto: não recebe imagem de referência, a cena é toda descrita pelo prompt, e aspect_ratio é obrigatório (seis opções: 1:1, 16:9, 9:16, 3:4, 4:3, auto).
• Três posicionamentos em uma família: Fast para esboços, versão padrão para produção diária, Ultra para refinar detalhes; os três IDs de modelo são usados por etapas no mesmo projeto.
• Sempre 1 imagem por vez: não há parâmetros de quantidade, dimensões em pixels ou formato de saída; para refazer, troque o seed.

Veja abaixo um resultado real da versão padrão:

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

(Em português: sala de estar escandinava iluminada pelo sol, sofá de linho, prateleiras de carvalho e uma planta monstera; fotografia de interiores com cara de revista. Proporção escolhida: 16:9.)

imagen-4.0, 16:9, 1280×720, $0.06.

Gerar com este prompt →

Como escolher entre os três modelos

	imagen-4.0-fast	imagen-4.0 (padrão)	imagen-4.0-ultra
Por imagem	$0.03	$0.06	$0.09
Posicionamento	Muitos testes de esboço, escolha de direção	Produção diária	Detalhes da imagem final, materiais e tipografia
$10 gera cerca de	333 imagens	166 imagens	111 imagens
Indicado para	Reuniões de pauta, rodadas de rascunho	Entrega de imagens de rotina	Versão final, cenas sensíveis a detalhes

Referência de orçamento: usando só a versão padrão, 1.000 imagens por mês custam cerca de $60.00; quanto mais testes de esboço forem para o Fast, menor a conta, e reserve o Ultra para a versão final.

Os três modelos são chamados da mesma forma, só muda o campo model; a estrutura de parâmetros é igual, apenas o tipo de seed difere (veja a tabela de parâmetros). Fast e Ultra têm cada um um tutorial de integração em inglês: Imagen 4 Fast API guide, Imagen 4 Ultra API guide. Para escolher prompts por cenário, veja o guia de prompts; a tabela completa de preços das três versões e o orçamento mensal estão na página de preços, e a comparação de dois conjuntos com os mesmos prompts entre Imagen 4 e Nano Banana 2.1 está na página de comparação.

Duas rotas para começar

Navegador em 3 passos: abra a página do modelo → cole o prompt e escolha a proporção → clique em gerar; a versão padrão custa $0.06 por imagem. Na primeira vez, recomendo gerar uma imagem no navegador para confirmar que o estilo atende à expectativa antes de escrever código.

API em 3 passos: POST /v1/tasks para enviar → receba o taskId → consulte GET /v1/tasks/<taskId> e, após success, baixe.

curl: a primeira imagem

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

Para trocar de versão, basta alterar model: imagen-4.0-fast ou imagen-4.0-ultra. O taskId da resposta é a credencial de consulta.

Python: enviar, consultar em polling, baixar

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# Envio: com Idempotency-Key, novas tentativas de rede não criam tarefas duplicadas
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Polling: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # endereço temporário, baixe e salve o quanto antes
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # nomeie a extensão conforme o formato realmente retornado
        f.write(img.content)
    print("saved")

Tabela de parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–5000 caracteres	Descrição do conteúdo da imagem
aspect_ratio	Sim	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	Proporção de saída, obrigatório
negative_prompt	Não	≤5000 caracteres	Conteúdo que não deve aparecer
seed	Não	Versão padrão e Ultra: string (≤500 caracteres); Fast: inteiro	Mesmos parâmetros e mesmo seed reproduzem a imagem

Os três modelos compartilham a mesma tabela de parâmetros. Campos fora da tabela no corpo da requisição retornam 400 diretamente.

Erros que você vai encontrar

Código de status	Significado	Como resolver
400 INVALID_REQUEST	Corpo da requisição inválido (falta prompt ou aspect_ratio, valor de enum errado, campo fora da tabela)	Ajuste o corpo da requisição conforme a tabela de parâmetros
402 INSUFFICIENT_QUOTA	Saldo insuficiente (sem cobrança)	Recarregue e tente de novo
429 RATE_LIMITED	Limite de requisições atingido	Reduza a frequência de envio
409 / 422 IDEMPOTENCY_KEY_*	Mesma chave de idempotência reenviada (em processamento / parâmetros inconsistentes)	Use uma nova Idempotency-Key
415 UNSUPPORTED_MEDIA_TYPE	Formato da requisição incorreto	Verifique Content-Type: application/json

Se a tarefa terminar em falha, os códigos de erro incluem CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT etc.; falhas não são cobradas e os créditos pré-reservados são devolvidos integralmente.

Antes de ir para produção

• Callback: envie no nível superior do corpo "callback": {"url": "https://..."}; ao atingir o estado final, a tarefa notifica seu serviço, dispensando o polling.
• Salve logo: output[0].url é um endereço temporário; baixe e armazene no seu próprio storage assim que receber.
• Declare a proporção explicitamente: aspect_ratio é obrigatório, não dependa do valor padrão; para conteúdo vertical em redes sociais, escolha 9:16.
• Tipo de seed por modelo: Fast recebe inteiro, versão padrão e Ultra recebem string.

Perguntas frequentes

Os três modelos são chamados da mesma forma?

Sim, só mude o campo model; o restante do código não precisa mudar.

Dá para especificar dimensões em pixels ou formato de saída?

Não. Não há parâmetros de dimensões em pixels nem de formato; a proporção de saída é definida por aspect_ratio, sempre 1 imagem por vez.

Falhas são cobradas?

Não. Os créditos pré-reservados são devolvidos integralmente após o estado final de falha.

O texto dentro da imagem é confiável?

Amplie e confira. Imagens do tipo pôster às vezes têm uma letra a mais ou um traço faltando; antes de publicar, amplie e revise a parte do texto.

Dá para misturar imagens das três versões em um mesmo projeto?

Sim. A lógica de prompt e proporção é comum.

Próximo passo: copie o prompt da sala de estar acima e teste uma imagem na página do modelo, depois escolha por cenário os modelos do guia de prompts para gerar imagens em lote.