API imagen-4.0-ultra: uma solicitação de texto para imagem que funciona

O Imagen 4 Ultra é a versão com o maior nível de detalhe da série Google Imagen 4. No hiapi, ele é executado como todos os outros modelos de imagem por meio da mesma API unificada de tarefas assíncronas para geração de texto para imagem. Este guia apresenta uma solicitação que realmente funciona — uma chamada curl real, um loop de polling em Python, os parâmetros que o servidor realmente aceita e os casos de erro verificados com solicitações reais. Todo o conteúdo a seguir foi executado e validado no endpoint de produção antes da publicação; o taskId de exemplo e a URL de saída vêm dessa execução.

O que você vai construir

Uma única chamada transforma um prompt de texto em uma imagem finalizada: envie a tarefa para POST /v1/tasks, faça polling até concluir e leia a URL da imagem em output[0].url. Você precisa de uma chave de API do hiapi — obtenha-a no seu painel e exporte-a:

export HIAPI_API_KEY="your-hiapi-key"

Exemplo mínimo funcional (curl)

O modelo aceita prompt e, opcionalmente, aspect_ratio. Crie a tarefa:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "Macro product photo of a matte ceramic coffee mug on a pale oak table, soft window light from the left, shallow depth of field, a few coffee beans in the foreground, no text, no logos",
      "aspect_ratio": "4:3"
    }
  }'

A chamada de criação retorna imediatamente um id de tarefa — a geração continua em segundo plano:

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

Faça polling da tarefa usando o id retornado:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Quando status for success, a imagem estará em output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

Essa execução foi concluída em cerca de 8 segundos e retornou um WebP (não PNG/JPEG). A URL fica em armazenamento temporário ("storage": "temp"), com expireAt definido para 7 dias depois — baixe-a em tempo hábil e não a utilize via hotlink.

Produção: Python com loop de polling

A resposta de criação não contém a imagem — apenas o taskId. Uma integração real envia a tarefa e depois faz polling (ou usa callback). Este script executa o ciclo completo e baixa o resultado imediatamente, pois a URL é temporária:

import os, time, requests

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

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

Pontos importantes para produção:

• Polling vs callback. O exemplo acima mostra polling. Para evitar polling, você pode anexar um objeto callback de nível superior ({"url": "...", "when": "final"}); quando a tarefa atingir um estado final, o hiapi enviará uma solicitação POST para você. Consulte o contrato de callback na documentação da API assíncrona unificada.
• Faça polling novamente com o id salvo, não recrie. A leitura de tarefas é idempotente; quando a conexão cair, tente novamente GET /v1/tasks/<id>, nunca faça outro POST (isso cobraria outra imagem).
• Baixe assim que houver sucesso. output[0].url é temporária (nesta execução, o TTL foi de 7 dias). Obtenha os bytes e envie para o seu próprio armazenamento.

Parâmetros que este modelo realmente aceita

imagen-4.0-ultra suporta apenas texto para imagem — não suporta imagem de referência (confirmado na página do modelo; nesta execução só foi testado texto para imagem). O schema de entrada é fechado: campos desconhecidos são rejeitados, portanto não é possível passar parâmetros extras secretamente.

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	1–5.000 caracteres. Uma string vazia falha (minLength: got 0, want 1).
aspect_ratio	enum	Não	Um de 1:1, 16:9, 9:16, 3:4, 4:3, auto. O padrão é 1:1.
negative_prompt	string	Não	Até 5.000 caracteres; descreve o que deve ser excluído.
seed	string	Não	Até 500 caracteres. É uma string — enviar um número é rejeitado.

Uma solicitação gera exatamente uma imagem.

Casos de erro verificados

Estes foram produzidos no endpoint real, portanto seu tratamento de erros pode contar com eles. Solicitações rejeitadas retornam HTTP 400, com envelope plano e sem taskId:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: aspect_ratio: value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'"}

Alguns comportamentos que vale considerar no código:

• O validador relata todos os erros de campo de uma vez, unidos por ; . Se você enviar um número em seed e um aspect_ratio inválido, receberá ambos em uma única mensagem: invalid input: seed: got number, want string; aspect_ratio: value must be one of .... Não presuma que há apenas um erro por resposta.
• Campos desconhecidos fazem a solicitação inteira falhar, com o erro <root>: additional properties '<name>' not allowed. O schema é fechado.
• Prompt vazio falha com o erro prompt: minLength: got 0, want 1.
• Um create bem-sucedido retorna code: 200 com data.taskId; uma rejeição retorna data: null. Ramifique com base nisso antes de tentar ler o id da tarefa.

Qual nível do Imagen 4 devo chamar?

imagen-4.0-ultra é o nível mais alto entre os três; escolha por tarefa, não por hábito (proporção, prompt negativo e seed não afetam o valor que você paga — consulte preços):

• Imagen 4 Fast —— o mais barato, ideal para rascunhos e exploração em lote de direções.
• Imagen 4 —— o nível intermediário do dia a dia, adequado para imagens de produto, estilo de vida e conteúdo.
• Imagen 4 Ultra (este modelo) —— o mais caro dos três, posicionado para detalhes de nível final: macrotexturas, renderização de materiais e tipografia, em cenários em que a imagem final precisa resistir a escrutínio. Escolha o Ultra quando a saída for entregável; use o Fast ou o nível básico durante a iteração.

Links relacionados

• Página do modelo Imagen 4 Ultra —— schema ao vivo, exemplos e preços.
• Documentação da API assíncrona unificada —— criação/listagem/obtenção de tarefas e contrato de callback.
• Início rápido —— autentique-se e execute sua primeira tarefa em poucos minutos.
• Preços —— custo por imagem de cada nível do Imagen 4.

Perguntas frequentes

Quantas imagens uma solicitação retorna? Uma. Na execução validada, o array output continha apenas um item.

Qual é o formato da saída? WebP. O arquivo retornado é um .webp em temp.hiapi.ai.

Quanto tempo a URL de saída fica válida? Cerca de 7 dias — expireAt é definido para 7 dias após a conclusão. Trate-a como um recurso temporário e baixe imediatamente.

Posso enviar uma imagem de referência? Não. imagen-4.0-ultra suporta apenas texto para imagem; a página do modelo lista imagem de referência como não suportada.

Por que minha solicitação retorna o erro "additional properties not allowed"? O schema de entrada é fechado. Envie apenas prompt, aspect_ratio, negative_prompt e seed; qualquer outra chave faz a solicitação inteira falhar.

O prompt negativo, a seed ou a proporção mudam o preço? Não. A cobrança é por imagem; esses parâmetros não afetam o custo.