how-tos

Ideogram 4.6 API para texto nas imagens e edições de alta precisão

Poyo.ai Team
8 min read
Share:

Ideogram 4.6 API: texto nas imagens e edições de alta precisão

A Ideogram 4.6 API foi concebida para um fluxo que a maioria das APIs de imagem resolve mal: gerar um cartaz com palavras exatas e, depois, alterar uma linha desse texto sem redesenhar o resto. Este guia prático cobre as duas metades com corpos de pedido: 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 o que aqui aparece corre contra o modelo Ideogram 4.6 na PoYo, e os números vêm do nosso teste do dia do lançamento, a 20 de novembro de 2026.

Parte 1: texto exato na imagem com a Ideogram 4.6 API

A documentação da PoYo dá uma única regra para o texto: coloque entre aspas no prompt o texto exato que deve aparecer na imagem. Descreva onde fica cada linha e qual o seu tamanho, da mesma forma que faria num briefing para um designer.

Este é o pedido 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
  }
}

Devolveu um PNG de 2304×3072 com cerca de 10.8 MB e foi cobrado a 40 créditos ($0.20), a tarifa 4K de qualidade alta. As três linhas entre aspas foram renderizadas tal como estavam escritas, incluindo a pequena linha em itálico. O mesmo prompt com quality: very_low e size: 3:4 (tarefa BS7M64COKT80JSLX) devolveu um rascunho de 768×1024 por 1.6 créditos ($0.008), também com o texto correto, mas com uma composição diferente.

Três hábitos tornam os pedidos com texto mais fiáveis em produção:

HábitoPorquê
Uma string entre aspas por cada linha de textoCada linha é uma unidade separada que pode verificar e editar mais tarde
Indique o tamanho e a posição de cada linha («título grande no topo», «uma linha mais pequena por baixo»)A hierarquia faz parte do pedido, não fica ao acaso
Verifique a saída antes de publicarA própria Ideogram aconselha: «Verifique a ortografia e o posicionamento no resultado final.»

A expansão do prompt está sempre ativa nesta API, por isso o modelo pode acrescentar detalhes que não pediu. No nosso cartaz, acrescentou um pequeno "EST. 1987" e um endereço web nos cantos inferiores. Se um layout só pode conter as suas palavras, diga-o no prompt e verifique o resultado, ou remova os extras com uma edição.

Parte 2: três formas de editar com ideogram-v4.6-edit

Cada edição recebe exatamente uma imagem de origem em image_urls e um prompt. As definições abaixo decidem quanto da imagem o modelo pode tocar. Se a sua aplicação permite que os utilizadores carreguem a origem, analisá-la primeiro evita tarefas falhadas; o guia de moderação de imagens mostra uma forma de o fazer.

ModoDefiniçõesO que é mantidoTamanho de saída
Edição normaledit_precision: regular (predefinição)A imagem é regenerada a partir do promptauto ou qualquer tamanho predefinido/personalizado sem máscara
Edição de alta precisãoedit_precision: high, context_window: noneOs píxeis inalterados são restauradosResolução da origem
Edição localizadaedit_precision: high, context_window: auto, mask_urlTodos os píxeis fora da região à volta da máscaraResolução da origem

A Ideogram afirma que o 4.6 «deixa muito menos desvio de píxeis fora das suas edições» e indica 90% em edições com máscara («alterar apenas a área pintada») contra 82% do Ideogram 4.5 na sua página do modelo. Estas são pontuações da Ideogram. Eis 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 cartaz de 2304×3072 da Parte 1. A saída foi de 2304×3072 com a nova linha da data. Uma comparação de píxeis com o original colocou todos os píxeis 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 ilustração e a pequena linha em itálico ficaram inalterados. O custo 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 ultrapassa 4,194,304 píxeis.

Duas regras a reter: 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 as dúvidas sobre onde a edição é aplicada. Tem de ter as mesmas dimensões que a origem, preto onde o modelo pode editar e branco onde tem de manter, e conter ambos. Este excerto de 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")

Carregue a máscara (URL público ou data URI em base64) e adicione-a ao pedido:

{
  "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 à volta da máscara é editada e a resolução da origem é mantida. Uma máscara demasiado grande recorre à edição da imagem inteira. context_window: auto sem mask_url e edit_precision: high é rejeitado, e uma máscara exige sempre size: auto. Pode acrescentar até 3 imagens de referência com uma máscara, por exemplo um logótipo ou uma amostra tipográfica, em reference_image_urls.

Parte 3: verificar a edição no seu pipeline

Se a sua aplicação promete que «só o texto mudou», verifique-o. 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 pretendia alterar, por exemplo a sua máscara. Se se estender muito para além dela, tente de novo com uma máscara e context_window: auto, ou com um prompt mais preciso.

Parte 4: edições em várias rondas e custo

Para uma série de alterações, envie cada resultado como a origem seguinte em image_urls e altere uma única coisa por pedido. A página da Ideogram descreve o 4.6 como feito para «continuar a refinar a mesma imagem ao longo de várias rondas». Cada ronda é uma tarefa separada, faturada pelo tamanho de saída:

Edição de uma origem...mediumhigh
Até 4,194,304 píxeis12 créditos ($0.06)44 créditos ($0.22)
Acima de 4,194,304 píxeis40 créditos ($0.20)120 créditos ($0.60)

Três alterações de texto em high no nosso cartaz 4K custariam 360 créditos ($1.80); numa versão de 1728×2304 do mesmo cartaz, 132 créditos ($0.66). Descarregue cada resultado: os ficheiros gerados são mantidos durante 3 dias. O artigo de preços tem mais orçamentos, e o guia da API tem um ciclo de polling que pode reutilizar em cada ronda.

Perguntas frequentes

Como coloco texto exato numa imagem com a Ideogram 4.6 API? Coloque cada linha entre aspas no prompt de um pedido ao ideogram-v4.6 e descreva o seu tamanho e posição. Verifique o resultado antes de publicar.

Como altero o texto de uma imagem existente com a Ideogram 4.6 API? Envie a imagem para 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 píxeis inalterados 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 faturadas por imagem de saída, consoante a qualidade e o escalão de tamanho. A máscara e até 3 referências estão incluídas.

Porque é que uma pequena edição de texto custou 120 créditos? Uma edição de alta precisão com qualidade high de uma origem acima de 4,194,304 píxeis usa a tarifa de edição 4K de qualidade alta. Edite uma origem mais pequena ou use medium (40 créditos em 4K, 12 em 2K).

Para a lista completa de parâmetros, consulte 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: