how-tos

Ideogram 4.6 API para texto na imagem e edições de alta precisão

Poyo.ai Team
8 min read
Share:

Ideogram 4.6 API: texto na imagem e edições de alta precisão

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ábitoPor quê
Uma string entre aspas por linha de textoCada 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 publicarA 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.

ModoConfiguraçõesO que é mantidoTamanho da saída
Edição regularedit_precision: regular (padrão)A imagem é regenerada a partir do promptauto ou qualquer tamanho preset/personalizado sem máscara
Edição de alta precisãoedit_precision: high, context_window: noneOs pixels não alterados são restauradosResolução da origem
Edição localizadaedit_precision: high, context_window: auto, mask_urlTodos os pixels fora da região em volta da máscaraResoluçã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...mediumhigh
Até 4,194,304 pixels12 créditos ($0.06)44 créditos ($0.22)
Acima de 4,194,304 pixels40 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.

Share: