
A Ideogram 4.6 API foi feita para um fluxo que a maioria das APIs de imagem resolve mal: gerar um pôster com palavras exatas e depois alterar uma linha desse texto sem redesenhar o resto. Este tutorial cobre as duas metades com corpos de requisição: texto na imagem com ideogram-v4.6 e edições de alta precisão, com máscara e localizadas com ideogram-v4.6-edit. Tudo aqui roda sobre o modelo Ideogram 4.6 na PoYo, e os números vêm do nosso teste do dia do lançamento, em 20 de novembro de 2026.
Parte 1: texto exato na imagem com a Ideogram 4.6 API
A documentação da PoYo dá uma regra para texto: coloque o texto exato da imagem entre aspas no prompt. Descreva onde cada linha fica e qual é o tamanho dela, do mesmo jeito que você passaria um briefing a um designer.
Esta é a requisição do nosso teste do dia do lançamento (tarefa M4WA9OIQXVV80DHG):
{
"model": "ideogram-v4.6",
"input": {
"prompt": "Screen-printed concert poster for \"NORTHBOUND JAZZ FESTIVAL\". Big bold condensed headline at the top, a stylized upright bass and saxophone silhouette over a river at dusk in deep teal, burnt orange and cream. Below the art, the line \"JUNE 12-14 · RIVERSIDE PARK\" and a smaller line \"Three nights. Twenty-one bands. Free entry before 6 PM.\" Fine paper grain, crisp letterforms, generous margins.",
"size": "2304x3072",
"quality": "high",
"n": 1
}
}
Ela retornou um PNG de 2304×3072 com cerca de 10.8 MB e foi cobrada em 40 créditos ($0.20), a tarifa 4K high. As três linhas entre aspas foram renderizadas como escritas, inclusive a pequena linha em itálico. O mesmo prompt com quality: very_low e size: 3:4 (tarefa BS7M64COKT80JSLX) retornou um rascunho de 768×1024 por 1.6 créditos ($0.008), também com o texto correto, mas com outra composição.
Três hábitos deixam as requisições com texto mais confiáveis em produção:
| Hábito | Por quê |
|---|---|
| Uma string entre aspas por linha de texto | Cada linha vira uma unidade separada que você pode conferir e editar depois |
| Diga o tamanho e a posição de cada linha ("título grande no topo", "uma linha menor abaixo") | A hierarquia faz parte da requisição, não fica por conta do acaso |
| Confira a saída antes de publicar | A própria Ideogram recomenda: "Confira a ortografia e o posicionamento no resultado final." |
A expansão do prompt está sempre ativa nesta API, então o modelo pode adicionar detalhes que você não pediu. No nosso pôster, ele adicionou um pequeno "EST. 1987" e um endereço web nos cantos inferiores. Se um layout deve conter só as suas palavras, diga isso no prompt e confira o resultado, ou remova os extras com uma edição.
Parte 2: três formas de editar com ideogram-v4.6-edit
Toda edição recebe exatamente uma imagem de origem em image_urls e um prompt. As configurações abaixo definem quanto da imagem o modelo pode tocar. Se o seu app permite que os usuários enviem a origem, filtrá-la antes evita tarefas com falha; o guia de moderação de imagens mostra uma forma de fazer isso.
| Modo | Configurações | O que é mantido | Tamanho da saída |
|---|---|---|---|
| Edição regular | edit_precision: regular (padrão) | A imagem é regenerada a partir do prompt | auto ou qualquer tamanho preset/personalizado sem máscara |
| Edição de alta precisão | edit_precision: high, context_window: none | Os pixels não alterados são restaurados | Resolução da origem |
| Edição localizada | edit_precision: high, context_window: auto, mask_url | Todos os pixels fora da região em volta da máscara | Resolução da origem |
A Ideogram diz que o 4.6 "deixa muito menos deriva de pixels fora das suas edições" e informa 90% em edições com máscara ("alterar só a área pintada") contra 82% do Ideogram 4.5 na sua página do modelo. Essas pontuações são da Ideogram. Veja a seguir o que nós medimos.
Edição de alta precisão: alterar uma linha de texto
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/northbound-poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high",
"n": 1
}
}
No nosso teste (tarefa 672JRU198S22NS8D), a origem era o pôster de 2304×3072 da Parte 1. A saída teve 2304×3072 com a nova linha da data. Um diff de pixels contra o original colocou todos os pixels alterados dentro de uma única caixa, de (471, 2699) a (1826, 2756): a linha da data, cerca de 1.1% da imagem. O título, a arte e a pequena linha em itálico não mudaram. A cobrança foi de 120 créditos ($0.60), porque uma edição de alta precisão mantém a resolução da origem e 2304×3072 está acima de 4,194,304 pixels.
Duas regras para lembrar: edit_precision: high exige size: auto (ou nenhum size) e rejeita background.
Edição com máscara: limitar a alteração a uma área
Uma máscara elimina a dúvida sobre onde a edição vai acontecer. Ela deve ter as mesmas dimensões da origem, preto onde o modelo pode editar, branco onde ele deve manter, e conter as duas cores. Este trecho em Python cria uma a partir de uma caixa:
from PIL import Image, ImageDraw
source = Image.open("poster.png")
mask = Image.new("L", source.size, 255) # white = keep
ImageDraw.Draw(mask).rectangle((440, 2660, 1860, 2800), fill=0) # black = edit
mask.save("date-line-mask.png")
Faça o upload da máscara (URL pública ou data URI em base64) e adicione-a à requisição:
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
Com context_window: auto, só a região em volta da máscara é editada e a resolução da origem é mantida. Uma máscara grande demais volta à edição da imagem inteira. context_window: auto sem mask_url e edit_precision: high juntos é rejeitado, e uma máscara sempre exige size: auto. Você pode adicionar até 3 imagens de referência com uma máscara, por exemplo um logo ou uma amostra de fonte, em reference_image_urls.
Parte 3: verifique a edição no seu pipeline
Se o seu app promete "só o texto mudou", confira. Este é o mesmo tipo de verificação que fizemos na edição do dia do lançamento:
from PIL import Image, ImageChops
before = Image.open("before.png").convert("RGB")
after = Image.open("after.png").convert("RGB")
assert before.size == after.size, "high-precision edits keep the source size"
diff = ImageChops.difference(before, after).convert("L").point(lambda v: 255 if v > 32 else 0)
box = diff.getbbox()
print("changed box:", box)
if box:
area = (box[2] - box[0]) * (box[3] - box[1])
print(f"box covers {area / (before.width * before.height):.2%} of the image")
Compare a caixa com a área que você pretendia alterar, por exemplo a sua máscara. Se ela se espalhar muito além disso, tente de novo com uma máscara e context_window: auto, ou com um prompt mais restrito.
Parte 4: edições em várias rodadas e custo
Para uma série de alterações, envie cada resultado de volta como a próxima origem em image_urls e altere uma coisa por requisição. A página da Ideogram descreve o 4.6 como feito para "continuar refinando a mesma imagem ao longo de várias rodadas". Cada rodada é uma tarefa separada, cobrada pelo tamanho da saída:
| Edição de uma origem... | medium | high |
|---|---|---|
| Até 4,194,304 pixels | 12 créditos ($0.06) | 44 créditos ($0.22) |
| Acima de 4,194,304 pixels | 40 créditos ($0.20) | 120 créditos ($0.60) |
Três alterações de texto em high no nosso pôster 4K custariam 360 créditos ($1.80); em uma versão de 1728×2304 do mesmo pôster, custariam 132 créditos ($0.66). Baixe cada resultado: os arquivos gerados ficam guardados por 3 dias. O post de preços tem mais orçamentos, e o guia da API tem um loop de polling que você pode reutilizar em cada rodada.
Perguntas frequentes
Como coloco texto exato em uma imagem com a Ideogram 4.6 API?
Coloque cada linha entre aspas no prompt de uma requisição ideogram-v4.6 e descreva o tamanho e a posição dela. Confira o resultado antes de publicar.
Como altero o texto de uma imagem existente com a Ideogram 4.6 API?
Envie a imagem para o ideogram-v4.6-edit com um prompt como: Change only the date line to "NEW TEXT". Keep everything else exactly the same. Defina edit_precision: high e size: auto.
Qual é a diferença entre edit_precision regular e high?
regular regenera a imagem a partir do prompt e permite um novo tamanho e background. high faz uma edição precisa, restaura os pixels não alterados e mantém a resolução da origem.
Uma máscara altera o preço da Ideogram 4.6 API? Não. As edições são cobradas por imagem de saída, conforme a faixa de qualidade e tamanho. A máscara e até 3 referências estão incluídas.
Por que uma pequena edição de texto custou 120 créditos?
Uma edição de alta precisão em qualidade high de uma origem acima de 4,194,304 pixels usa a tarifa de edição 4K high. Edite uma origem menor ou use medium (40 créditos em 4K, 12 em 2K).
Para a lista completa de parâmetros, veja a referência da Ideogram 4.6 Edit API. Para um conjunto de padrões de prompt testados, leia o guia de prompts da Ideogram 4.6 API.