API imagen-4.0-fast: uma solicitação de geração de imagem por texto que funciona

Imagen 4 Fast é o nível de velocidade da família Google Imagen 4 e, no hiapi, a geração de imagem por texto é feita pela mesma API de tarefas assíncronas unificada usada por todos os outros modelos de imagem. Este guia traz uma solicitação que realmente funciona: uma chamada curl real, um laço de polling em Python, o schema de entrada fechado exato e os casos de erro verificados em execuções online. Tudo abaixo foi executado contra o endpoint de produção antes da publicação; o taskId e a URL de saída nos exemplos vêm dessa execução.

O que você vai implementar

Uma chamada que transforma um prompt de texto em uma imagem pronta: envie a tarefa para POST /v1/tasks, faça polling até a conclusão e leia a URL da imagem. Você precisa de uma chave de API do hiapi (crie uma no console e mantenha algum crédito pré-pago na conta — consulte preços). Não é necessário SDK; todos os exemplos aqui usam HTTP puro.

Solicitação mínima funcional (curl)

Crie a tarefa. O id do modelo é imagen-4.0-fast e, neste nível, aspect_ratio é obrigatório (mais detalhes abaixo):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

A chamada de criação retorna apenas um identificador de tarefa — não a imagem:

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

Consultar o resultado (Python)

Com o taskId em mãos, consulte GET /v1/tasks/<id> até o status atingir um estado terminal. Este é o laço que realmente executei:

import os, time, requests

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

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

Na minha execução, o status passou por handling → archiving → success em cerca de 12 segundos, e a resposta do estado terminal foi assim:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

Uma tarefa retorna uma imagem WebP. O estado archiving é normal — ele permanece por um instante e depois muda para success.

Schema de entrada (o que o servidor realmente aceita)

O objeto input é um schema fechado. Ele aceita apenas os seguintes campos:

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	Não vazio; uma string vazia retorna minLength: got 0, want 1.
aspect_ratio	enum	Sim	Um de 1:1, 16:9, 9:16, 3:4, 4:3, auto. Sem valor padrão.
seed	integer	Não	Para execuções reproduzíveis. Deve ser um número JSON, não uma string.
negative_prompt	string	Não	Descreve o que você quer evitar na imagem.

Este modelo não tem os campos resolution ou size — o tamanho de saída segue o aspect_ratio. Qualquer campo fora desta tabela é rejeitado.

Casos de erro verificados (as armadilhas)

Isto não é suposição — cada um é uma resposta 400 real capturada contra o endpoint de produção.

1. Falta de aspect_ratio. Esta é a maior armadilha ao copiar trechos do Imagen 4 básico ou do nível Ultra, porque lá aspect_ratio tem padrão 1:1. No Fast não há valor padrão:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed enviado como string. Passe-o como número:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. Campo desconhecido (aqui, resolution) — o schema fechado rejeita qualquer conteúdo extra:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

Observe o formato: falhas de validação são HTTP 400 com error_code: "INVALID_REQUEST", sem taskId, e o message agrega todos os erros de campo em uma única string separada por ; — portanto leia a mensagem inteira, não apenas a primeira frase.

Fast em comparação com os outros níveis da família Imagen 4

O hiapi hospeda três níveis do Imagen 4 na mesma API de tarefas; apenas o id do model muda, então o corpo da solicitação acima funciona em todos os níveis:

• imagen-4.0-fast — o nível de velocidade (página do modelo) e a opção de menor custo da família. Indicado para iteração de prompts, exploração de conceitos e exploração em lote de direções, ou seja, gerar muitos candidatos e manter alguns poucos.
• imagen-4.0 — o nível padrão Imagen 4.
• imagen-4.0-ultra — o nível de maior detalhe, para imagens finais de nível de entrega.

Um fluxo de trabalho prático: prototipe no Fast e depois troque a string de model por imagen-4.0-ultra para a renderização final, sem alterar nenhum outro código. Compare o preço atual por imagem na página de preços.

Considerações para produção

• Polling vs. webhook. O laço acima é polling. Em produção, a API de tarefas do hiapi também oferece suporte a webhook: adicione um objeto callback de nível superior (no mesmo nível de model/input) contendo url e when: "final", e o hiapi fará POST dos detalhes da tarefa quando ela atingir um estado terminal. Antes de depender disso, leia a documentação da API assíncrona para conhecer as convenções de entrega e repetição.
• Não reenvie quando a rede estiver instável. Cada criação de tarefa retorna um novo taskId — não há desduplicação de prompts. Se uma consulta de polling falhar brevemente, consulte novamente o taskId que você já salvou; só faça um novo POST se nunca tiver recebido o taskId.
• As URLs de saída expiram. output[].url fica em temp.hiapi.ai e seu expireAt é cerca de 7 dias depois (o exemplo acima expira em 2026-10-28). Baixe os bytes imediatamente para o seu próprio armazenamento; não faça hotlink.

Conteúdo relacionado

• Página do modelo Imagen 4 Fast
• Imagen 4 Ultra — nível de maior detalhe, mesma estrutura de solicitação
• Imagen 4 (básico)
• Documentação da API de tarefas assíncronas unificada
• Preços

Perguntas frequentes

O Imagen 4 Fast exige um endpoint ou SDK diferente? Não. É apenas POST /v1/tasks com "model": "imagen-4.0-fast" — o mesmo endpoint usado por todos os modelos de imagem e vídeo do hiapi. Troque de nível alterando o id do modelo.

Por que minha solicitação retorna 400 dizendo “missing required field aspect_ratio”? O Fast não tem proporção de aspecto padrão (diferente do básico e do Ultra). Sempre envie aspect_ratio a partir do enum 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

Posso definir resolução ou tamanho da imagem? Não — o modelo não tem os campos resolution ou size; o tamanho de saída segue o aspect_ratio. Enviar resolution retorna additional properties 'resolution' not allowed.

seed é string ou número? Número. "seed": 7 funciona; "seed": "7" retorna seed: got string, want integer.

Por quanto tempo a URL de saída é válida? Cerca de 7 dias (expireAt). Baixe e armazene imediatamente.