Como usar ideogram-v3-character pela API HiAPI: guia com curl + Python

O que é o ideogram-v3-character e quando usá-lo

O ideogram-v3-character é um modelo de geração de imagens na HiAPI focado em consistência de personagem. Em vez de tratar cada geração como um prompt independente, ele permite fornecer uma imagem de referência do personagem, para que as renderizações seguintes mantenham o mesmo rosto, vestuário e identidade geral.

Use-o quando quem é tão importante quanto o que faz:

• Storyboards e quadrinhos: o mesmo personagem aparece em vários painéis.
• Variantes de assets de jogos: gerar poses, expressões ou roupas diferentes para um personagem principal.
• Mascotes de marca: precisam manter aparência consistente em muitos cenários e fundos diferentes.
• Direção de arte iterativa: refinar o personagem ao longo de várias rodadas de ajustes sem perder a semelhança.

Se você só precisa de uma ilustração avulsa e não se importa em corresponder a imagens anteriores, um modelo genérico de texto para imagem é mais simples. A estrutura extra trazida pela imagem de referência é justamente o motivo pelo qual vale a pena adicionar campos de requisição ao ideogram-v3-character.

O modelo é exposto, como os demais, pelo endpoint unificado de geração de imagens da HiAPI, então a estrutura da requisição soa familiar: você envia um payload JSON, recebe a referência de job de uma tarefa assíncrona e faz polling até o resultado ficar pronto. Este tutorial foca em como executar esse fluxo corretamente.

Antes de enviar a requisição: configuração e autenticação

Antes da primeira chamada, você só precisa preparar algumas coisas.

1. Chave de API

Crie uma chave de API no painel da sua conta HiAPI. Trate-a como confidencial — ela autoriza cada uma das suas requisições e é cobrada na sua conta.

2. Manuseio de credenciais via variáveis de ambiente

Nunca codifique a chave diretamente nos arquivos-fonte nem a envie para o git. Use variáveis de ambiente:

export HIAPI_API_KEY="your_api_key_here"

Em Python, você pode lê-la assim:

import os
api_key = os.environ["HIAPI_API_KEY"]

Se você usa um arquivo .env no desenvolvimento local, adicione-o ao .gitignore antes de fazer qualquer outra coisa.

3. URL da imagem de referência

Como a consistência de personagem depende da imagem de referência, prepare uma imagem que possa ser passada por URL. Garanta que essa URL seja publicamente acessível ou acessível de outra forma pela API — links privados atrás de autenticação falham. Imagens quadradas ou verticais que mostrem claramente o rosto do personagem funcionam melhor.

4. Forma de fazer requisições HTTP

curl na linha de comando ou um ambiente Python com requests instalado — qualquer um dos dois basta. Os exemplos abaixo assumem que você tem um deles.

Com esses quatro itens prontos, você pode enviar sua primeira requisição.

Anatomia de uma requisição curl funcional, linha por linha

Abaixo está uma requisição completa que envia um job ideogram-v3-character para a HiAPI. Substitua os placeholders pelos seus próprios valores.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "一位友好的机器人机械师站在阳光充足的工作坊里，手持扳手，四分之三视角",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

O papel de cada parte

• POST /v1/images/generations — o endpoint unificado de geração de imagens da HiAPI. Todos os modelos usam o mesmo caminho.
• Authorization: Bearer $HIAPI_API_KEY — autentica a chamada. O shell expande a variável de ambiente que você definiu anteriormente.
• Content-Type: application/json — você está enviando um corpo JSON, então precisa declará-lo.
• model — seleciona ideogram-v3-character. Sem isso, a requisição não sabe para qual modelo rotear.
• prompt — descrição da cena. Descreva pose, ambiente, iluminação e atmosfera; deixe a identidade do personagem para a imagem de referência.
• reference_images — array de URLs de imagem. Para um único personagem, normalmente basta um item.
• aspect_ratio — forma da saída. Combine com o uso pretendido (quadrado, vertical etc.).
• num_images — quantas variantes gerar por job.

Um envio bem-sucedido retorna um corpo JSON contendo o identificador do job. Anote esse valor — a etapa de polling vai precisar dele. A resposta também pode conter um campo de status indicando que o job está na fila ou em processamento. Se o status já for terminal, o resultado pode vir embutido diretamente na resposta; caso contrário, continue o polling.

A mesma requisição em Python

Abaixo está exatamente a mesma chamada em Python. Ela lê a chave da variável de ambiente, envia a requisição e imprime a referência do job.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "一位友好的机器人机械师站在阳光充足的工作坊里，手持扳手，四分之三视角",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Notas sobre a versão em Python

• timeout=60 evita que o script fique pendurado indefinidamente em redes ruins.
• raise_for_status() converte respostas não-2xx em exceções, para que você perceba imediatamente problemas de autenticação e validação.
• Extração do ID do job — a HiAPI retorna o identificador do job no corpo da resposta. Dependendo da estrutura da resposta, ele pode estar em id ou job_id; o exemplo verifica ambos, mas você deve primeiro inspecionar uma resposta real e então codificar o nome de campo correto para maior clareza.

O payload é deliberadamente idêntico ao exemplo curl. Copiar o corpo JSON de um lado para o outro é uma boa verificação de sanidade ao depurar: se um funciona e o outro não, o problema está na camada de transporte, não no modelo.

Manipulando imagens de referência para consistência de personagem

A imagem de referência é exatamente o que diferencia o ideogram-v3-character dos modelos comuns de texto para imagem. Cuidar bem delas resolve a maior parte do trabalho.

Como fornecer imagens de referência

O campo reference_images é um array de URLs. Cada URL deve apontar para uma imagem que a API possa buscar diretamente. Se você armazena uploads de usuários, sirva-os a partir de um bucket ou CDN que permita requisições GET não autenticadas, ou gere uma URL assinada que permaneça válida durante a execução do job.

Dicas de imagens de referência que realmente mantêm a consistência

• Apenas um personagem por imagem de referência. Fotos em grupo tornam difícil saber qual rosto preservar.
• Rosto claro e bem iluminado. Evite sombras pesadas, ângulos extremos e oclusões.
• Pose neutra ou característica. Vistas frontais ou em três quartos preservam melhor a identidade.
• Se você quer preservar o vestuário, ele deve ser consistente nas imagens de referência — o modelo reproduz o que vê.
• Resolução importa, mas não exagere. Uma imagem de tamanho razoável e rosto nítido supera uma imagem enorme e desfocada.

Mantendo o personagem reconhecível em várias gerações

Quando você gerar um segundo cenário para o mesmo personagem, reutilize a mesma imagem de referência, não a saída gerada anteriormente. Encadear imagens geradas pode acumular pequenos desvios. Se precisar de uma nova referência — por exemplo, com roupa diferente — gere-a uma vez, inspecione-a e então reutilize esse arquivo como nova referência para jobs subsequentes.

Validando a consistência

Gere duas ou três variantes do mesmo personagem em poses diferentes e compare lado a lado. Se o rosto ou o vestuário divergirem, geralmente a causa é uma imagem de referência fraca ou ambígua. Antes de mexer no prompt, reforce a imagem de referência.

Jobs assíncronos: enviar, fazer polling e obter resultados

A geração de imagens leva tempo, então a HiAPI processa de forma assíncrona. O padrão é sempre o mesmo: enviar, capturar o ID do job, fazer polling até o job atingir um estado terminal e então ler a URL de saída.

Ciclo de vida do job

1. Envio — você envia a requisição do exemplo anterior.
2. Na fila — o job foi aceito e aguarda capacidade.
3. Processando — o modelo está renderizando.
4. Concluído ou falhou — estado terminal; o resultado (ou erro) está disponível.

Polling em Python

Após capturar o job_id, faça polling no endpoint de jobs:

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

Obtendo o resultado

Quando o job termina, o corpo da resposta contém a saída — normalmente um array de URLs de imagem ou uma única URL, além de metadados. Baixe a imagem dessa URL o quanto antes; algumas URLs têm validade limitada. Se precisar de armazenamento de longo prazo, copie o arquivo para o seu próprio bucket imediatamente após o sucesso do job.

Etiqueta de polling

• Backoff. Um intervalo de dois segundos serve para jobs curtos; se estiver fazendo polling de muitos jobs, aumente o intervalo ou use jitter.
• Limite as tentativas. A proteção max_attempts evita loops infinitos e oferece ao código um caminho de falha explícito.
• Não faça polling mais rápido do que o necessário. Cada polling é uma requisição; martelar o endpoint não fará a renderização terminar mais cedo.

Erros comuns e como diagnosticá-los

Quando algo dá errado, o caminho mais rápido costuma ser isolar se o problema está na sua requisição, na imagem de referência ou no próprio job.

Falhas de autenticação

401 significa que a chave está ausente, mal formatada ou revogada. Verifique se a variável de ambiente está realmente definida no shell ou processo que executa a requisição. Armadilha comum: definir a variável em um terminal e executar o script em outro.

Erros de validação

400 quase sempre aponta para o payload. Verifique:

• Se o campo model é exatamente ideogram-v3-character.
• Se reference_images é um array, não uma string.
• Se cada URL do array é publicamente acessível.
• Se aspect_ratio usa um valor suportado.

Se estiver em dúvida, envie um payload mínimo — apenas model, prompt e reference_images — e adicione os campos de volta um a um.

Jobs que nunca terminam

Se o polling ultrapassar o limite de tentativas, não apenas tente de novo sem critério. Verifique se a resposta de status do job contém alguma mensagem. Causas comuns são URL de referência inacessível ou fila sobrecarregada. Reenvie uma vez; se travar novamente, simplifique o prompt e a imagem de referência.

Imagem de referência silenciosamente ignorada

O job conclui, mas o personagem não corresponde. Isso normalmente é problema da imagem de referência, não do código: a URL pode estar retornando uma página de erro, um PDF ou uma imagem de placeholder. Busque a URL você mesmo no navegador para confirmar que ela retorna a imagem esperada e com o content type correto.

Limites de taxa

429 significa que você está enviando requisições rápido demais. Use backoff exponencial; se estiver gerando em lote, escalone os envios em vez de disparar tudo de uma vez.

Checklist rápido

• A chave está definida no ambiente correto?
• A URL de referência é acessível sem autenticação?
• Os campos do payload estão com a grafia correta?
• O polling tem limite e backoff?
• A saída foi baixada antes de sua URL expirar?

Percorrer esse checklist em ordem resolve rapidamente a maioria das falhas. Depois que a primeira execução ponta a ponta funcionar, guarde-a como exemplo sabidamente bom e compare qualquer nova requisição com ela. Ao escalar para muitos personagens e cenas, só esse hábito já economiza tempo.