Como usar a Character API do Ideogram 3.0? Gere sua primeira imagem de personagem em 5 minutos

TL;DR

• Ideogram 3.0 Character é um modelo de geração de personagem a partir de imagem de referência: envie 1 imagem de referência do personagem, escreva um prompt de cena e o mesmo rosto e o mesmo figurino aparecem na nova cena. Abra a página do modelo para testar online; novos usuários ganham 200 créditos ao se cadastrar.
• O preço é por imagem: TURBO $0.09, BALANCED $0.13, QUALITY $0.18. A imagem de referência não é cobrada e falhas não são cobradas (veja a página de preços).
• A chamada usa a API /v1/tasks do HiAPI: envie a tarefa e receba o taskId, use-o para consultar o resultado e, após sucesso, baixe a imagem em output[0].url.

O que ele faz

• Geração com consistência de personagem: uma imagem de referência fixa o personagem, mantendo rosto e figurino consistentes, e você troca a cena à vontade.
• Serve para ilustração e realismo: style aceita AUTO / REALISTIC / FICTION, funcionando tanto para personagens fotográficos quanto ilustrados.
• Formato segue a imagem de referência: referência vertical gera 3:4 (864×1152), referência horizontal gera 16:9 (1328×752), sem precisar informar parâmetros de tamanho.
• Endpoint de edição complementar: ideogram-v3-character/edit usa uma máscara para desenhar o personagem em uma região específica de uma imagem existente, sem alterar o restante.

A imagem abaixo é um resultado real (a referência era um personagem de ilustração em formato horizontal):

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

(Em português: este personagem explorador caminhando por um mercado noturno iluminado por lanternas, segurando um copo de papel com macarrão quente, barracas com luz quente dos dois lados, estilo ilustração de livro infantil, sem texto, sem placas.)

ideogram-v3-character, TURBO, 16:9, 1328×752, $0.09.

Gerar com este prompt →

Como escolher entre os dois endpoints

	ideogram-v3-character	ideogram-v3-character/edit
O que faz	Gera o personagem em uma nova cena do zero	Desenha o personagem na região da máscara de uma imagem existente
Entradas obrigatórias	prompt + 1 imagem de referência	prompt + imagem original + máscara + 1 imagem de referência
Preço (TURBO / BALANCED / QUALITY)	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
Saída	WebP, formato segue a imagem de referência	WebP, dimensões seguem a imagem original
Indicado para	Pôsteres, séries, imagens de cenas em sequência	Trocar ou adicionar personagens em imagens prontas

Convenção da máscara: preto = redesenhar, branco = preservar; a proporção da máscara e da imagem original deve ser a mesma. O endpoint de edição não aceita negative_prompt; se enviado, retorna erro 400.

Dois caminhos para começar

No navegador, 3 passos: abra a página do modelo → envie a imagem de referência do personagem e cole o prompt → clique em gerar. TURBO custa $0.09 por imagem.

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

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": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Para o endpoint de edição, troque model por ideogram-v3-character/edit e adicione image_url (imagem original) e mask_url (máscara) em input:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

O taskId na resposta é o comprovante para consultar o resultado.

Python: enviar, consultar e baixar

import time, uuid, requests

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

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# 提交：带 Idempotency-Key，网络重试不会重复建任务
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 轮询：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"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

Tabela de parâmetros (ideogram-v3-character)

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–5000 caracteres	Descreve a cena em que o personagem deve aparecer, não a aparência do personagem (a aparência vem da imagem de referência)
reference_image_urls	Sim	Exatamente 1, JPEG / PNG / WebP, ≤10 MB	Imagem de referência do personagem; o formato dela define o formato da saída
rendering_speed	Não	TURBO / BALANCED / QUALITY, padrão BALANCED	Define o nível de qualidade e o preço
style	Não	AUTO / REALISTIC / FICTION, padrão AUTO	REALISTIC tende a textura fotográfica; FICTION mantém o aspecto de ilustração
seed	Não	Inteiro 0–2147483647	Com os mesmos parâmetros e mesmo seed, reproduz a imagem
expand_prompt	Não	Padrão true	Expande o prompt automaticamente; envie false para seguir o texto literalmente
negative_prompt	Não	≤5000 caracteres	Conteúdo que você não quer que apareça

O endpoint de edição tem dois campos obrigatórios adicionais fora da tabela, image_url e mask_url, e não aceita negative_prompt. Campos fora da tabela no corpo da requisição geram 400 imediatamente (additional properties ... not allowed).

Erros que você vai encontrar (mensagens originais da API)

O que você fez	Retorno
Não enviou prompt	400 invalid input: prompt: missing required field "prompt"
Enviou 2 imagens de referência	400 invalid input: reference_image_urls: maxItems: got 2, want 1
Erro de digitação em rendering_speed	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
Enviou um campo desconhecido para a API	400 invalid input: <root>: additional properties 'foo' not allowed
Enviou negative_prompt no endpoint de edição	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
Saldo insuficiente	402 insufficient account balance; top up and retry

Reenviar com o mesmo Idempotency-Key retorna 409 (em processamento) ou 422 (parâmetros inconsistentes); tente novamente com uma nova key.

Cuidados antes de ir para produção

• Callback: envie no nível raiz 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, não o trate como link permanente.
• Declare sempre o nível e o formato: envie rendering_speed explicitamente em cada chamada (se omitido, é cobrado como BALANCED); o formato da saída é definido pela imagem de referência, então prepare uma referência vertical para cenas verticais.
• Use uma chave de idempotência por tarefa em lote: cada envio deve ter um Idempotency-Key único; ao repetir por falha de rede com a mesma key, você atinge a mesma tarefa, sem criar tarefas duplicadas nem cobrar créditos duas vezes.

Perguntas frequentes

A imagem de referência pode ser uma URL?

Pode. Basta ser um endereço http/https acessível; JPEG, PNG e WebP são aceitos, com no máximo 10 MB.

Quantas imagens de referência posso enviar?

Exatamente 1; é uma regra rígida, e enviar duas gera erro 400 imediatamente. Para trocar de personagem, troque a imagem de referência.

Preciso enviar parâmetros de tamanho?

Não. O formato da saída segue a imagem de referência: referência vertical gera 864×1152, referência horizontal gera 1328×752.

A forma de chamar os dois endpoints é a mesma?

É. Basta mudar model e os campos dentro de input.

Falhas são cobradas?

Não; os créditos pré-cobrados são totalmente reembolsados após o estado final de falha.

Próximo passo: use o prompt do mercado noturno acima para testar uma imagem na página do modelo e depois escolha prompts por cenário no guia de prompts; os três níveis de preço e a tabela de orçamento estão na página de preços.