Como usar a API do Ideogram 4.5? Geração, edição e consulta de tarefas

TL;DR

• O Ideogram 4.5 é uma família de geração de imagens a partir de texto com prioridade na tipografia: ideogram-v4.5/text-to-image gera pôsteres, logotipos, embalagens bilíngues e outras imagens com texto; ideogram-v4.5/image-to-image usa o Precise Edit para alterar textos com precisão, mudar o estilo com imagens de referência e redesenhar áreas com máscara. Você pode escolher a tarefa na página do modelo ou chamar a API conforme descrito abaixo.
• O preço é por imagem e varia conforme o nível de qualidade: LOW $0.043, MEDIUM (padrão) $0.086, HIGH $0.3145; o nível de edição VERY_LOW começa em $0.0115; atualmente cada requisição gera 1 imagem e num_images só pode ser 1. Veja detalhes na página de preços.
• A chamada usa a API /v1/tasks do HiAPI: após enviar, leia data.taskId e depois consulte data.status; em caso de sucesso, baixe o endereço com type=image a partir de data.output.

O que ele pode fazer

• Organizar a hierarquia do texto na imagem: coloque entre aspas o texto que deve aparecer e indique separadamente as posições de título, subtítulo, data e elenco; confira cada palavra após a geração.
• Explorar composições com tarefas de imagem única: cada requisição gera 1 imagem; ajuste o prompt ou a seed e envie várias tarefas para comparar direções.
• API de edição complementar: o Precise Edit (edit_precision=high) pode ser usado para alterações pontuais como nomes de marca e datas; confira as áreas preservadas em comparação com a imagem original.
• Imagens de referência + máscara: até 4 imagens de referência (3 quando há máscara); na máscara, preto = redesenhar, branco = manter.

Abaixo está um resultado real gerado (nível LOW):

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(Significado em chinês: pôster de marca minimalista e moderno para uma conferência de design, com o título enorme em negrito "DESIGN FORWARD" centralizado, o subtítulo menor "Typography Summit 2026" abaixo, layout em grade suíça, paleta de laranja quente e azul-marinho profundo, formas geométricas e letras nítidas e definidas. Tamanho escolhido: landscape_16_9.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, $0.043.

Gerar com este prompt →

Como escolher entre as duas APIs

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
O que faz	Gera uma imagem com composição tipográfica a partir de texto	Edita uma imagem existente
Entrada obrigatória	prompt	image_url + prompt
Nível de qualidade	low / medium / high	very_low / low / medium / high
Parâmetros especiais	num_images: 1, enable_prompt_expansion	edit_precision (Precise), reference_image_urls, mask_url
Tamanho	6 predefinições, padrão square_hd	auto (padrão) ou 6 predefinições; com máscara / Precise só pode ser auto
Indicado para	Pôsteres, logos, embalagens, novos rascunhos de letreiros	Alterar texto, trocar cores, versões sazonais, redesenho local

Fluxo típico: gere um pôster de marca e depois use o Edit para alterar o nome da marca ou a data para a versão do cliente. Gerar um LOW custa $0.043 mais um Precise LOW para alterar o texto por $0.043, total de $0.086 por conjunto.

Dois caminhos para começar

Navegador em 3 passos: abra a página do modelo → cole o prompt e escolha o nível de qualidade → clique em gerar.

API em 3 passos: POST /v1/tasks para enviar → leia data.taskId → GET /v1/tasks/<taskId> para consultar data.status e, ao chegar em success, baixe.

curl: a primeira imagem

Primeiro defina no terminal HIAPI_IDEMPOTENCY_KEY como o identificador exclusivo desta operação; ao repetir a mesma requisição, mantenha esse valor. O exemplo usa explicitamente LOW, tamanho horizontal e expansão ativada.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

API de edição: troque model por ideogram-v4.5/image-to-image e envie a imagem de origem e a instrução. Abaixo o Precise Edit é usado para solicitar alteração de texto e preservação do layout; o resultado ainda precisa ser conferido em comparação com a imagem original:

Esta tarefa de edição define ainda HIAPI_EDIT_IDEMPOTENCY_KEY; não reutilize a chave da tarefa de geração.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python: enviar, consultar e baixar

Instale primeiro requests e defina HIAPI_API_KEY; no primeiro envio, defina também HIAPI_IDEMPOTENCY_KEY, usando um valor independente para cada nova operação e mantendo-o igual nas repetições do mesmo envio. O programa imprime primeiro o ID da tarefa; após uma interrupção, defina HIAPI_TASK_ID para continuar a consulta e o download sem enviar a geração novamente.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

Se ocorrer um erro de rede na consulta ou no download, preserve o ID da tarefa já impresso e retome; o script não reenvia automaticamente a requisição de criação. O exemplo tem limite de consulta de 600 segundos, com espera de 3 segundos a cada vez; o download grava primeiro um arquivo .part e só renomeia para o nome definitivo após concluir.

Tabela de parâmetros

Geração ideogram-v4.5/text-to-image

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–10000 caracteres	Estrutura em quatro partes: que imagem fazer → texto e cores → layout → textura e restrições
quality	Não	low / medium / high, padrão medium	low para exploração em lote, medium no dia a dia, high para versões finais com muito texto pequeno
image_size	Não	6 predefinições, padrão square_hd	Sem largura e altura personalizadas
num_images	Não	Fixo em 1	Cada tarefa gera 1 imagem
enable_prompt_expansion	Não	Padrão true	Expansão do prompt; false desativa a expansão, mas ainda é preciso conferir o texto do resultado
seed	Não	Inteiro	Reprodução com os mesmos parâmetros

Edição ideogram-v4.5/image-to-image

Campo	Obrigatório	Valores	Descrição
image_url	Sim	Endereço da imagem	Imagem de origem
prompt	Sim	1–10000 caracteres	Instrução de edição; especifique o que alterar e o que manter
edit_precision	Não	regular / high, padrão regular	high = Precise Edit, indicado para alterações pontuais de texto
quality	Não	very_low / low / medium / high, padrão medium	very_low só pode ser usado com regular
image_size	Não	auto ou 6 predefinições, padrão auto	Com máscara ou Precise só pode ser auto
reference_image_urls	Não	Até 4 imagens	Com máscara, até 3 imagens
mask_url	Não	Endereço da imagem	Preto = redesenhar, branco = manter
num_images	Não	Fixo em 1	Cada tarefa gera 1 imagem
seed	Não	Inteiro

Campos dentro de input que não constem na tabela de parâmetros deste modelo retornam 400; model, callback e outros campos de nível superior seguem o formato da API de tarefas.

Erros que você vai encontrar

Código de status	Significado	Como tratar
400 INVALID_REQUEST	Corpo da requisição inválido (falta prompt ou image_url, valor de enumeração incorreto, campo fora da tabela)	Corrija o corpo da requisição conforme a tabela de parâmetros
402 INSUFFICIENT_QUOTA	Saldo insuficiente (sem cobrança)	Recarregue e tente novamente
429 RATE_LIMITED	Limite de requisições atingido	Reduza a frequência de envio
409 IDEMPOTENCY_KEY_PROCESSING	Tarefa com a mesma chave em criação	Aguarde e tente novamente com a mesma chave e o mesmo corpo de requisição
422 IDEMPOTENCY_KEY_MISMATCH	A mesma chave foi usada com corpo de requisição diferente	Restaure o corpo original; só use uma nova chave para uma nova tarefa de negócio

Uma falha no estado final da tarefa pode incluir códigos como CONTENT_POLICY_VIOLATION, TASK_FAILED e TASK_TIMEOUT. Preserve o taskId e a mensagem de erro e confira a cobrança com base no estado final da tarefa e nos registros da conta; não trate falha de consulta ou de download como falha de geração.

Atenção antes de ir para produção

• Callback: envie no nível superior do corpo "callback": {"url": "https://..."} para ser notificado automaticamente no estado final.
• Salve os resultados logo: os links de resultado em data.output têm prazo de validade; baixe o quanto antes após o sucesso.
• Tarefas de imagem única e idempotência: cada execução gera 1 imagem; ao repetir a mesma requisição de negócio por timeout, mantenha a chave de idempotência original; só use uma nova chave para uma nova tarefa de negócio.
• Texto pequeno em chinês: compare os níveis de qualidade com o texto real; revise palavra por palavra antes da entrega, pois medium ou high não substituem a conferência.

Perguntas frequentes

Quantas imagens no máximo por requisição?

Atualmente geração e edição produzem 1 imagem por vez, e num_images só pode ser 1. Envie tarefas separadas para várias direções.

O nível de qualidade padrão é LOW?

Não. O padrão é MEDIUM, a $0.086 por imagem; para LOW a $0.043 por imagem, passe explicitamente quality: "low".

Qual modo usar para trocar apenas o nome da marca e a data?

Pode-se usar o Precise Edit, passando explicitamente edit_precision: "high", quality: "low" e image_size: "auto"; $0.043 por imagem.

O que as áreas pretas e brancas da máscara representam?

A área preta é redesenhada e a branca é mantida. A máscara deve ter o mesmo tamanho da imagem de origem; ao usar máscara, escolha auto em image_size.

É preciso trocar a chave de idempotência após um timeout no envio?

Não troque a chave ao repetir a mesma requisição de negócio; mantenha o mesmo Idempotency-Key e o mesmo corpo. Só use uma nova chave quando realmente precisar de uma nova tarefa.

Próximo passo: pegue o prompt do pôster DESIGN FORWARD e gere uma imagem na página do modelo, depois use uma instrução Precise para trocar o título pelo nome do seu próprio evento. Leitura complementar: três níveis de preço e orçamento · 4 exemplos de prompts de edição.

Se quiser começar direto a criar letreiros ou pôsteres de evento, copie esta coleção de exemplos de prompts.