Blogue

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

Nov 18, 2026
Imagem de capa do blog: sobre um fundo verde-escuro profundo, dois grupos de faixas largas e achatadas se entrelaçam formando um padrão de trama técnica, com inserções verticais em tom de latão, em composição geométrica contida.
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.

As três entradas não são camadas paralelas: imagem de origem, máscara e imagem de referência de personagem são responsáveis por regiões diferentes do quadro de saída; o diagrama expressa essa divisão por meio de três linhas de convergência.

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:

  1. Escolha uma imagem nítida, de frente ou quase de frente, com o rosto desobstruído;
  2. Evite contraluz forte, filtros pesados e fotos com várias pessoas (o modelo não consegue decidir quem alinhar);
  3. 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;
  4. 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

  • style tem os valores AUTO, REALISTIC, FICTION, padrão AUTO. Use REALISTIC para pessoas realistas, FICTION para ilustrações estilizadas, e mantenha AUTO se 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.

Os três níveis são como variações de densidade da mesma trama: quanto mais acima, mais densa a trama, mais detalhes e mais lenta.

Lista de verificação antes do envio

Conferir item por item conforme o contrato pode evitar a maioria das falhas antes do envio:

  • prompt nã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 com http:// ou https://;
  • mask_url també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 (style e rendering_speed usam os valores em maiúsculas listados no contrato);
  • Se seed foi definido, confirme que é um inteiro entre 0 e 2147483647;
  • Se expand_prompt foi desativado, confirme que o prompt em 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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API