Ideogram
Ideogram V3 Character
ideogram-v3-character
Use a imagem de referência para fixar o mesmo personagem, mantendo a consistência do rosto e do vestuário entre mudanças de cena, pose e iluminação, e aproveitando a vantagem de composição tipográfica dentro da imagem do Ideogram
Experimentar ideogram-v3-character
Entrada
Criações
Ver todas as criaçõesSaída
imagePreços
ideogram-v3-character per image
| Especificações | Preço unitário |
|---|---|
| TURBO | $0.090 |
| BALANCED | $0.130 |
| QUALITY | $0.180 |
Visão geral
ideogram-v3-character é um modelo de geração de imagens que usa uma imagem de referência como âncora visual do personagem: ao fornecer uma foto nítida do personagem, ele preserva os traços faciais, o penteado, as roupas e as proporções corporais da pessoa em várias gerações, enquanto permite alterar cena, pose, iluminação e fundo por meio de prompts. É indicado para desenvolvedores e equipes criativas que precisam reutilizar o mesmo visual em storyboards de quadrinhos, séries de imagens para redes sociais ou desdobramentos de mascotes de marca, e também mantém a capacidade do Ideogram de diagramar textos dentro da imagem.
Destaques principais
- Basta uma única imagem de referência para fixar o personagem — com apenas uma imagem do personagem em JPEG, PNG ou WebP como entrada, o modelo a usa como âncora visual para manter a aparência consistente.
- Troca de cenário sem trocar a pessoa — ao fixar a aparência do personagem, é possível ajustar amplamente cena, pose, iluminação e fundo por meio de prompts.
- Controle de parâmetros reproduzível — suporta seed, prompt negativo e níveis de velocidade de renderização, facilitando geração estável em lote e ajuste de detalhes e ritmo conforme a necessidade.
Descrição das capacidades
Consistência do personagem com imagem de referência: usando uma imagem de referência do personagem como entrada, o resultado preserva rosto, penteado, roupas e proporções físicas, adequado para conteúdos seriados que exigem reutilizar o mesmo visual em várias imagens.
Transformação de cena guiada por prompt: com o personagem fixado, descreva a nova cena e pose com um prompt de até 5000 caracteres, e use o prompt negativo para excluir elementos indesejados.
Geração reproduzível: permite definir uma seed aleatória, facilitando reproduzir o mesmo resultado durante ajustes ou produção em lote e reduzindo o custo de seleção.
Escolha de nível de renderização: oferece três níveis de velocidade de renderização — TURBO, BALANCED e QUALITY —, permitindo ao desenvolvedor equilibrar velocidade e qualidade conforme o ritmo de geração e as exigências de detalhe.
Cenários de aplicação
- Autores de quadrinhos e storyboards: cenas contínuas do mesmo personagem — insira a imagem de referência do personagem e a descrição de cada quadrinho para produzir imagens de storyboard visualmente coerentes, que entram diretamente no fluxo de diagramação e pós-produção.
- Operação de redes sociais: identidade visual unificada em séries de conteúdo — gere em lote imagens para diferentes temas a partir de uma imagem de referência fixa do personagem, mantendo o protagonista visual consistente entre várias edições de conteúdo.
- Equipes de marca: desdobramento de mascotes em diferentes cenários — use a imagem do mascote para gerar materiais derivados em diferentes campanhas, estações ou pôsteres, destinados à veiculação de materiais de marketing.
Limitações e recomendações de escolha
A consistência do personagem não é absoluta: em cenas complexas, poses exageradas e variações de expressão, rosto e detalhes ainda podem apresentar desvios visíveis. A qualidade da imagem de referência afeta diretamente o resultado; recomenda-se usar imagens do personagem com rosto nítido, iluminação uniforme e pouca oclusão. Se for necessário apenas uma imagem criativa isolada, sem necessidade de personagem fixo, modelos comuns de texto para imagem são mais adequados. Para projetos comerciais com exigência altíssima de fidelidade ao personagem, recomenda-se validar a consistência com uma pequena amostra antes de gerar em lote.
Novidades
Ver o changelog →- Novo modelo Adicionado ideogram-v3-character geração de consistência de personagem e ideogram-v3-character/edit…
Perguntas frequentes
Ver todas as perguntas →-
Quais são os requisitos da máscara?
A máscara deve ter a mesma proporção (largura/altura) da imagem original; as áreas pretas serão redesenhadas e as áreas brancas serão preservadas. É mais natural que a área seja ligeiramente maior que o contorno do personagem.
-
Qual é o tamanho da saída?
A saída acompanha o tamanho da imagem original; por exemplo, uma imagem original de 1024×768 gera um resultado de 1024×768.
-
Já há uma pessoa na imagem original, posso substituí-la?
Sim, pinte a pessoa que deseja substituir na máscara e descreva a ação do novo personagem no prompt; as pessoas e o fundo fora da máscara serão preservados.
-
Qual formato a máscara deve usar?
Use uma imagem com a mesma proporção da imagem original, com a área a ser redesenhada pintada em preto sobre fundo branco; o exemplo desta página usa uma máscara PNG.
Criar uma tarefa de geração
https://api.hiapi.ai/v1/tasks Cabeçalhos
AuthorizationstringObrigatórioChave de API da conta. Obrigatória em toda requisição. Exemplo: Bearer YOUR_HIAPI_API_KEY. Obter chave de API
Content-TypestringOpcionalO corpo da requisição é sempre interpretado como JSON; se enviado, apenas application/json (charset opcional) é aceito — qualquer outro valor retorna 415. Exemplo: application/json.
Idempotency-KeystringOpcionalChave de idempotência, até 255 bytes. Retries com a mesma chave da mesma conta criam a tarefa apenas uma vez; replays retornam o taskId original.
Em timeouts de rede ou retries automáticos do cliente, a mesma chave cria a tarefa apenas uma vez, sem cobrança duplicada (escopo = a conta da chave de API). Use um identificador de negócio exclusivo (ex.: "order-42"); replays retornam o taskId original e as chaves expiram 24 h após a primeira requisição. A matriz completa de cenários está na introdução da API assíncrona unificada.
Corpo
modelstringObrigatórioValor fixo atual: ideogram-v3-character
routestringOpcionalValor fixo atual: default
inputobjectObrigatório
Objeto de parâmetros de negócio para ideogram-v3-character e a rota default — veja a tabela de parâmetros abaixo.
seedintegerOpcionalmin 0max 2147483647Semente aleatória usada para resultados de geração reproduzíveis; o valor é um número inteiro e a mesma semente reproduz a mesma saída.
stylestringOpcionalPadrão: "AUTO"Tipo de estilo que controla o estilo geral da imagem gerada; padrão AUTO.
AUTOREALISTICFICTIONpromptstringObrigatóriominLength 1maxLength 5000Prompt de cena usado para descrever o personagem de referência, com limite de 5000 caracteres.
expand_promptbooleanOpcionalPadrão: trueDefine se o MagicPrompt é ativado para expandir o prompt; padrão true.
negative_promptstringOpcionalmaxLength 5000Prompt negativo que especifica o conteúdo a excluir da imagem, com limite de 5000 caracteres.
rendering_speedstringOpcionalPadrão: "BALANCED"Nível de velocidade de renderização: TURBO é o mais rápido e mais barato, QUALITY tem os detalhes mais ricos, e a cobrança varia conforme o nível; padrão BALANCED.
TURBOBALANCEDQUALITYreference_image_urlsarrayObrigatóriominItems 1maxItems 1Array de imagens de referência do personagem, que deve conter exatamente uma imagem de referência do personagem, nos formatos JPEG, PNG ou WebP, com no máximo 10 MB por imagem.
Array [ string ]
callbackobjectOpcional
Configuração de notificação de estado terminal. Se omitida, sem callback: consulte a tarefa por conta própria.
Informe callback.url na criação e o HiAPI fará POST no seu serviço no estado terminal, sem polling. O corpo do callback replica a estrutura do detalhe da tarefa; assinatura, retries e idempotência estão descritos na introdução da API assíncrona unificada.
urlstringObrigatórioObrigatória se callback estiver presente. No estado terminal é enviado um POST para esta URL; deve ser uma URL http(s) válida.
whenstringOpcionalPadrão: "final"Atualmente só há suporte a final — notifica tanto em success quanto em fail.
finalstoragestringOpcionalPadrão: "temp"Nível de armazenamento de artefatos: temp (padrão, ~7 dias) ou persistent (longo prazo, cobrado por tamanho). Saldo insuficiente ou limite excedido ⇒ rebaixamento silencioso para temp; o nível efetivo aparece na resposta de detalhes.
temppersistentExemplos de requisição
# Envia uma tarefa assíncrona; retorna um taskId imediatamente (sem esperar a geração)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v3-character",
"input": {
"style": "AUTO",
"prompt": "…",
"expand_prompt": true,
"rendering_speed": "BALANCED",
"reference_image_urls": "…"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "ideogram-v3-character",
input: {
"style": "AUTO",
"prompt": "…",
"expand_prompt": true,
"rendering_speed": "BALANCED",
"reference_image_urls": "…"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "ideogram-v3-character",
"input": {
"style": "AUTO",
"prompt": "…",
"expand_prompt": True,
"rendering_speed": "BALANCED",
"reference_image_urls": "…"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} Obter detalhes da tarefa
https://api.hiapi.ai/v1/tasks/:id Campos da resposta
taskIdstringObrigatórioID da tarefa, sempre com prefixo tk-hiapi-.
modelstringObrigatórioNome completo resolvido do modelo. Tarefas enviadas com o parâmetro route retornam base@route (ex.: gpt-image-2/text-to-image@ext); caso contrário, igual ao nome enviado.
routestringOpcionalPresente apenas se o parâmetro route explícito foi usado; ecoa o valor enviado.
statusstringObrigatórioEstado da tarefa.
queued Na fila, ainda não iniciada.
handling Em processamento.
archiving Processamento concluído, preparando artefatos.
success Terminal: concluído, artefatos disponíveis (retorna output).
fail Terminal: falha (retorna error).
Após o envio, acompanhe status: success e fail são terminais, os demais não. Faça polling a cada 1–3 s até o estado terminal. Em caso de sucesso, baixe os artefatos em output[].url e transfira antes de expireAt; para retenção longa, use storage: "persistent" na criação.
creatednumberObrigatórioMomento de criação da tarefa (segundos Unix).
completednumberObrigatórioSegundos Unix do estado terminal; 0 enquanto não terminal.
outputarrayOpcional
Presente apenas com status == success. Lista de artefatos — sempre um array; uma tarefa pode retornar vários types ao mesmo tempo (ex.: video + first_frame).
Array [ object ]
Itens do array
urlstringObrigatórioURL do artefato, baixável diretamente.
typestringObrigatórioValores possíveis no momento: video, image, audio, first_frame, last_frame, thumbnail; poderão ser ampliados.
expireAtnumberObrigatórioSegundos Unix de disponibilidade do artefato; baixe ou transfira antes da expiração.
errorobjectOpcional
Presente apenas com status == fail.
codestringObrigatórioCódigo de erro de negócio.
messagestringObrigatórioDescrição do erro.
Exemplos de resposta
Sucesso
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} Em processamento (não final)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Falhou
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} Artigos
Ver todos os artigos →-
Tutorial
Tutorial de kandinsky-6.0-pro/image-to-video na HiAPI: curl + Python
Faça uma requisição de imagem para vídeo funcional na HiAPI: do upload do primeiro quadro ao polling assíncrono e ao download final
-
Tutorial
Como chamar kling-4.0/image-to-video na HiAPI: curl, Python e polling
-
Tutorial
Como chamar hailuo-2.3/text-to-video pela API HiAPI: curl, Python e exemplos de requisição executáveis
-
Tutorial
Como chamar hailuo-2.3-fast/image-to-video pela API HiAPI: curl e Python na prática
A primeira requisição executável do nível rápido e econômico de geração de vídeo a partir de imagem — do ID do modelo ao download do MP4
-
Tutorial
Usar Kandinsky 6.0 Pro text-to-video na HiAPI: tutorial de curl e Python
Demonstração prática com foco na requisição: montar a chamada de prompt para clipe de vídeo, enviar a requisição, consultar o status de conclusão e baixar o resultado
-
Tutorial
recraft-v4.1-flash geração de imagens por texto na prática: 5 cenários de negócio de alto valor e pontos de integração
Partindo de um custo de US$ 0,01 por imagem, planeje como aplicar a geração de imagens em negócios reais
-
Avaliação comparativa
hailuo-2.3-fast/image-to-video comparação lado a lado: como escolher modelos de imagem para vídeo e pontos de migração
-
Tutorial
Como usar kling-4.0/text-to-video através da API HiAPI: curl, Python e um exemplo de requisição executável
Guia prático para desenvolvedores: prompts cinematográficos, áudio sincronizado, polling assíncrono e download da saída
-
Avaliação comparativa
Comparação lado a lado do Recraft v4.1 Flash em text-to-image: guia de seleção e migração para desenvolvedores
Com um custo de $0.01 por imagem e capacidade de text-to-image pura, avalie se ele é adequado para seu pipeline de geração de imagens
Modelos relacionados
Ver todos os modelos →Mesmo tipo
-
Ideogram V4.5 Ideogram $0.011 /imagem -
FLUX 3 Image Black Forest Labs $0.041 /imagem -
BRIA Product Shot Bria $0.058 /imagem -
Ideogram V4 Ideogram $0.050 /imagem -
Grok Imagine Image 2.0 xAI $0.052 /imagem -
FLUX 1.1 Pro Black Forest Labs $0.050 /imagem -
Krea 3 Krea $0.036 /imagem -
Muse Image 1.0 Meta $0.015 per task -
Nano Banana Google $0.021 /imagem -
FLUX.2 Klein 9B Black Forest Labs $0.0086 /imagem -
FLUX.1 Kontext Max Black Forest Labs $0.071 /imagem -
Qwen Image 2.1 Alibaba $0.020 /imagem





