Guia de uso
Guia de integração do Ideogram V3 Character Edit: como preparar a imagem de origem, a máscara e a imagem de referência de personagem
Três entradas de imagem com funções distintas: envie edições locais conforme os campos do contrato e verifique item por item a consistência do personagem e as bordas
Nesta página
O que cada uma das três entradas de imagem controla
Antes de integrar o ideogram-v3-character/edit, separe as responsabilidades dos três campos de imagem; todas as etapas de preparação seguintes ficarão mais claras.
- Imagem de origem
image_url: determina “o que será alterado na cena”. Ela fornece a composição original, o fundo e a posição do sujeito, sendo a base de toda a operação de edição. - Máscara
mask_url: determina “onde alterar”. Ela delimita apenas a região a ser repintada; o conteúdo fora dela deve ser preservado. - Imagem de referência de personagem
reference_image_urls: determina “qual é a aparência do personagem”. Ela fornece as características faciais do personagem para alinhar o resultado da repintura ao personagem de referência.
Não misture os limites entre os três: a imagem de origem não é a imagem de referência de personagem, e a imagem de referência de personagem não substitui a imagem de origem; a máscara é uma restrição espacial, não uma descrição de conteúdo. Delegar as características do personagem à imagem de referência, escrever o conteúdo da cena no prompt e a área de modificação à máscara é a divisão que menos gera erros. Se misturar (por exemplo, enviar apenas a imagem de personagem sem máscara, ou usar a máscara para “sugerir” a aparência do personagem), você perderá a base de julgamento ao diagnosticar problemas.
No nível do contrato, a imagem de origem e a máscara são campos de URL em string, e a imagem de referência de personagem é um campo de array; os tipos diferentes também indicam usos diferentes: os dois primeiros formam um par espacial um-para-um, enquanto o último é uma fonte independente de descrição de personagem.

Pontos essenciais para preparar a imagem de origem e a máscara
image_url e mask_url são campos obrigatórios, no formato URI, devendo começar com http:// ou https:// (padrão do contrato ^https?://), com comprimento mínimo de 1.
A proporção deve ser idêntica
A única restrição geométrica rígida do contrato para ambos é: a máscara deve manter a mesma proporção da imagem de origem. Isso não é uma sugestão, mas um pré-requisito; ao preparar os materiais, o mais seguro é gerar localmente a máscara nas dimensões da imagem de origem e enviá-las juntas, sem esperar que o servidor faça o alinhamento.
Semântica da máscara: delimitar apenas a região de repintura
A máscara marca os locais “permitidos para repintura”. Portanto:
- As partes que devem ser preservadas não devem cair dentro da região da máscara;
- O sujeito que precisa ser alterado (por exemplo, troca de roupa, mudança de pose) deve estar completamente dentro da máscara, evitando que as bordas sejam cortadas;
- A máscara não deve ser fragmentada demais; pequenos blocos dispersos dificultam a compreensão da intenção de edição pelo modelo.
Disponibilidade das URLs
Ambos os campos são URLs remotas; antes de enviar, confirme que o link pode ser acessado anonimamente, que não há redirecionamentos quebrados e que não requer autenticação. Para a máscara, recomenda-se usar uma imagem com canal alfa ou com contraste claro entre preto e branco, evitando ambiguidade nas bordas causada por gradientes semitransparentes.
Especificações e restrições da imagem de referência de personagem
reference_image_urls é um campo de array obrigatório, e o contrato impõe restrições claras: minItems: 1, maxItems: 1, ou seja, é necessário e suficiente uma única imagem. Enviar duas ou nenhuma será considerado entrada inválida; isso contrasta com a intuição de muitas pessoas sobre “referência com múltiplas imagens” e é um ponto fácil de errar na integração.
Formato e tamanho
- Formatos suportados: JPEG, PNG, WebP;
- Tamanho máximo por imagem: 10 MB.
Recomendações para escolha da imagem
A imagem de referência de personagem serve para fornecer características estáveis do personagem; portanto:
- Escolha uma imagem nítida, de frente ou quase de frente, com o rosto desobstruído;
- Evite contraluz forte, filtros pesados e fotos com várias pessoas (o modelo não consegue decidir quem alinhar);
- Corpo inteiro e meio corpo têm trade-offs: use meio corpo ou mais para detalhes de vestuário, e corpo inteiro para o visual geral;
- Não use uma imagem com fundo complexo para “sugerir” a cena — a cena deve ser descrita no
prompt.
Embora o array comporte apenas um elemento, ele ainda deve ser enviado como array, por exemplo, envolvendo uma única URL em um item, em vez de colocar a string diretamente.
Como combinar campos obrigatórios e opcionais
Há quatro campos obrigatórios: prompt, image_url, mask_url, reference_image_urls. Os ajustes opcionais incluem expand_prompt, style, seed, rendering_speed.
O prompt descreve a nova cena, não instruções de edição
A definição de prompt no contrato é crucial: “descreve a cena em que o personagem de referência se encontra, ou seja, o conteúdo da imagem a ser gerado nesta edição”, com comprimento de 1 a 5000 caracteres. Ou seja, não escreva instruções operacionais como “troque a roupa dela por um casaco vermelho”, mas sim descrições de cena como “ela está em uma rua após a chuva, usando um casaco vermelho, com neons refletidos no chão molhado”. A área de edição é responsabilidade da máscara; o prompt é responsável pelo conteúdo da cena em si.
expand_prompt ativado por padrão
expand_prompt é um interruptor booleano, padrão true; quando ativado, o MagicPrompt expande automaticamente o prompt. Isso significa que a descrição curta que você envia será reprocessada pelo modelo. Na fase de diagnóstico, recomenda-se manter o padrão e, após entender a diferença entre descrições longas e resultados da expansão, decidir se deve desativá-lo.
style e seed
styletem os valoresAUTO,REALISTIC,FICTION, padrãoAUTO. UseREALISTICpara pessoas realistas,FICTIONpara ilustrações estilizadas, e mantenhaAUTOse não tiver certeza.seedé um inteiro, de 0 a 2147483647, usado para reproduzir o resultado de geração do mesmo prompt. Ao comparar “mesma entrada com parâmetros diferentes”, fixar o seed elimina a interferência da aleatoriedade.
Escolha do nível de rendering_speed
rendering_speed é uma enumeração de string, padrão BALANCED, com três níveis:
- TURBO: geração mais rápida, adequada para validar rapidamente a área da máscara e se o personagem corresponde na fase de rascunho;
- BALANCED: nível padrão, meio-termo entre velocidade e detalhes, ponto de partida para integrações do dia a dia;
- QUALITY: detalhes mais ricos, adequado para a rodada final antes da imagem definitiva.
A lógica de escolha é alternar conforme a fase, não fixar de uma vez: primeiro use TURBO para confirmar que a geometria e a direção do personagem estão corretas, depois use BALANCED ou QUALITY para refinar os detalhes. Assim, você não gasta tempo em renderizações de alta qualidade durante a depuração repetida.
É importante destacar: os três níveis têm diferenças na cobrança (cobrança por nível de geração); consulte o painel de preços do site para valores específicos, pois este artigo não detalha números. Ao diagnosticar problemas de entrada de imagem, fixar o nível padrão reduz uma variável.

Lista de verificação antes do envio
Conferir item por item conforme o contrato pode evitar a maioria das falhas antes do envio:
-
promptnão vazio e com no máximo 5000 caracteres; o conteúdo é uma descrição de cena, não uma instrução de edição; -
image_urlé um link acessível anonimamente começando comhttp://ouhttps://; -
mask_urltambém é acessível e mantém a mesma proporção da imagem de origem; -
reference_image_urlsé um array com exatamente 1 item; - A imagem de referência está em JPEG/PNG/WebP e não excede 10 MB;
- A grafia e os valores de enumeração dos campos opcionais estão corretos (
styleerendering_speedusam os valores em maiúsculas listados no contrato); - Se
seedfoi definido, confirme que é um inteiro entre 0 e 2147483647; - Se
expand_promptfoi desativado, confirme que opromptem si já está suficientemente completo.
Esta lista também é o primeiro passo na solução de problemas: se algum item não for atendido, corrija a entrada em vez de ajustar repetidamente a descrição.
Abordagem para diagnosticar desvios de personagem e problemas de borda
Quando o resultado gerado não for o esperado, classifique o problema primeiro e depois ajuste de forma direcionada; isso é mais eficaz do que reenviar a imagem inteira.
Tipo 1: personagem não se parece
Manifesta-se como desvio de traços faciais, penteado e tipo físico em relação à referência. Direções de ajuste:
- Troque a imagem de referência: use uma imagem frontal mais nítida, melhor iluminação, sujeito único;
- Verifique se a imagem de referência foi cortada ou comprimida excessivamente;
- Complemente a descrição do personagem no
prompt(roupa, postura, idade, estilo), para que texto e imagem se confirmem; - Reduza a complexidade da cena para evitar que elementos de fundo roubem os detalhes do personagem.
Tipo 2: bordas borradas
Manifesta-se como alteração inesperada do conteúdo fora da máscara, ou aparecimento de emendas e fantasmas nas bordas da máscara. Direções de ajuste:
- Primeiro confirme que a proporção da imagem de origem e da máscara é estritamente idêntica;
- Verifique se a máscara incluiu partes que deveriam ser preservadas;
- Garanta que o sujeito caia completamente dentro da máscara, evitando cortes nas bordas;
- Use bordas de máscara mais nítidas, reduzindo transições semitransparentes.
Não ajuste os dois tipos de problema ao mesmo tempo: para problemas de personagem, altere a imagem de referência e a descrição; para problemas de borda, altere a máscara e a geometria. Altere apenas uma variável por vez para saber qual item surtiu efeito.
Do exemplo à integração
Transformar os requisitos do contrato acima em um fluxo resume-se a quatro passos: prepare a imagem de origem e a máscara com a mesma proporção, escolha uma imagem de referência de personagem compatível, descreva a nova cena com um prompt contextualizado e verifique os campos conforme a lista antes de enviar.
O ponto de entrada para integração está na página do modelo; as definições de campos e valores de enumeração prevalecem na página, e você pode compará-las item por item com a lista deste artigo: Página do modelo Ideogram V3 Character Edit. Com os materiais preparados corretamente, os ajustes posteriores é que fazem sentido.
Artigos relacionados
Ver todos os artigos →-
Guia de uso
Guia de introdução ao gpt-6.2-sol: limites de capacidade, integração via API e noções de precificação por token
Decisões de integração e pontos práticos para equipes de engenharia
-
Guia de uso
Guia de introdução ao gpt-6.2-astra: limites de capacidade do modelo de texto, pontos de integração e controle de custos
-
Guia de uso
Guia de introdução ao Tripo H3.1: três modos de entrada, parâmetros e como escolher o preço
Decisão de integração e controle de custos na geração 3D para desenvolvedores