digitalsamba/ideogram4

Skill Ideogram 4

Geração de texto-para-imagem com Ideogram 4 (9,3B, pesos abertos, lançado em junho de 2026). Seu superpoder é a renderização de texto na imagem de melhor da classe — supera modelos muito maiores (FLUX.2 dev 32B, Qwen-Image 20B, Hunyuan 80B) na renderização de letreiros legíveis, logotipos, legendas e texto de múltiplas linhas — além do controle exato de paleta de cores e caixas delimitadoras.

Essa vantagem está bloqueada por trás de um formato de legenda JSON estruturada. Um prompt em texto simples produz resultados no nível do FLUX e perde o propósito inteiro de usar este modelo. Esta skill ensina o Claude a atuar como o expansor de "prompt mágico" — transformando um pedido casual do usuário na legenda JSON na qual o Ideogram 4 foi treinado.

Backend: O kit de ferramentas usa a API hospedada v4 da Ideogram (não pesos auto-hospedados). A API aceita um json_prompt estruturado, então tudo o que esta skill ensina se aplica diretamente — Claude constrói a legenda, a ferramenta a envia como json_prompt. Os planos pagos da API incluem uma licença comercial, que os pesos auto-hospedáveis (não comerciais) não possuem — é por isso que usamos a API. O custo é de ~$0,03/imagem (turbo) a ~$0,10/imagem (qualidade).

Quando Usar Esta Skill

Recorra ao Ideogram 4 (em vez do FLUX.2) quando a imagem precisar de:

• Texto legível na imagem — cartões de título, miniaturas, fundos de terço inferior, letreiros, logotipos, cartões de citação, CTAs com um título embutido
• Cores exatas da marca — condicionamento de paleta de cores hexadecimais, por elemento
• Layout controlado — caixas delimitadoras posicionam texto/objetos em regiões específicas
• Texto multilíngue na imagem

Use FLUX.2 quando: a imagem não tiver texto crítico, você precisar de saída com licença comercial, ou apenas quiser um fundo atmosférico rápido. O FLUX aceita prompts em linguagem natural simples; o Ideogram quer JSON. Consulte tools/flux2.py.

A Única Coisa a Acertar

Sempre emita uma legenda JSON estruturada, nunca uma frase simples. O modelo foi treinado exclusivamente em legendas JSON que nomeiam cada elemento explicitamente. Claude é um melhor expansor do que o prompt mágico gratuito hospedado da Ideogram (a própria documentação deles observa que o enviado "não é o mesmo usado em produção"), então construa a legenda você mesmo usando esta skill em vez de passar texto puro.

Legenda mínima válida:

{"high_level_description":"Um barco à vela ao pôr do sol em águas calmas.","style_description":{"aesthetics":"sereno, quente, hora dourada","lighting":"contraluz da hora dourada","photo":"grande angular, f/8","medium":"fotografia","color_palette":["#FF6B35","#F7C59F","#004E89"]},"compositional_deconstruction":{"background":"Oceano calmo no horizonte baixo com céu laranja-rosado.","elements":[{"type":"obj","desc":"Vela triangular branca silhuetada contra o sol poente."}]}}

O esquema completo, regras estritas de ordenação de chaves e o sistema de coordenadas bbox estão em prompting.md. Exemplos trabalhados de cartão de título/miniatura/cartão de citação estão em examples.md.

Referência Rápida — tools/ideogram4.py

Invólucro leve sobre a API hospedada v4 da Ideogram. Precisa de IDEOGRAM_API_KEY no .env (chave de developer.ideogram.ai). --json posta a legenda como o campo json_prompt da API (sem prompt mágico no servidor — Claude é o expansor); --prompt posta text_prompt.

# Legenda JSON escrita à mão (caminho recomendado para texto/layout) — Claude escreve caption.json
uv run tools/ideogram4.py --json caption.json --output title.png

# Legenda da entrada padrão (Claude pode canalizá-la diretamente)
cat caption.json | uv run tools/ideogram4.py --json - --output title.png

# Prompt simples — o prompt mágico do servidor da Ideogram expande (mais fraco; prefira --json)
uv run tools/ideogram4.py --prompt "Cartão de título: 'REVISÃO DE ENGENHARIA DE IA' branco negrito sobre escuro" --output title.png

# Injeta cores hex da marca na paleta da legenda (modo JSON)
uv run tools/ideogram4.py --json caption.json --brand digital-samba --output cta.png

# Nível de qualidade + resolução
uv run tools/ideogram4.py --json caption.json --speed QUALITY --resolution 2048x2048 --output slide.png

Ideogram 4.5 (opt-in)

--model 4.5 envia as mesmas flags para o Ideogram 4.5 na API v2 (POST /v2/image/generate/ideogram-4-5, multipart como a chamada v1). Foi testado ao vivo: legendas JSON renderizam texto quase perfeito; prompts simples adicionam texto de preenchimento distorcido, então sempre envie uma legenda JSON para o 4.5. O Ideogram 4 permanece o padrão porque os tamanhos do 4.5 devem ser múltiplos de 32, o que descarta o tamanho exato do YouTube 1280x720 (/thumbnail usa o 4.0 para isso).

uv run tools/ideogram4.py --model 4.5 --json caption.json --speed QUALITY --resolution 1440x2560 --output card.png

• Prompt: ambos os modos vão no campo único prompt do 4.5. --json envia a legenda como JSON compacto. O 4.5 lê o formato de legenda do Ideogram 4, e uma legenda válida pula o prompt mágico do servidor. O texto --prompt é expandido pelo prompt mágico, como na v1.

• --speed mapeia para quality: TURBO, DEFAULT e QUALITY ao mesmo preço que no Ideogram 4, e FLASH, que não tem preço no Ideogram 4, para baixo (preços listados da Ideogram, verificados em 2026-10-12; tamanhos 1K e 2K custam o mesmo):

  --speed	4.5 quality	Por imagem
  FLASH, TURBO	low	$0,03
  DEFAULT (padrão)	medium	$0,06
  QUALITY	high	$0,10

  O nível very_low do 4.5 precisa de imagens de origem, então a ferramenta nunca o envia. No --model 4, FLASH ainda é enviado como está, mas a documentação da Ideogram diz que atualmente retorna HTTP 400.

• --resolution é enviado como size: auto, ou LARGURAxALTURA com ambos os lados múltiplos de 32 e pelo menos 256px, no máximo 2048x2048 pixels no total, e uma proporção de aspecto de no máximo 6:1. Omita-o e a Ideogram escolhe um tamanho a partir do prompt. A ferramenta verifica essas regras antes de chamar a API e sai com código 2 quando um tamanho as viola. 1440x2560 (o tamanho do cartão 9:16) e 2048x2048 passam. Seis predefinições do Ideogram 4 não passam, e o erro sugere uma substituição: 720x1280 (1440x2560), 1280x720 (2560x1440), 720x1440 (1440x2880), 1440x720 (2880x1440), 1296x3168 (1280x3072), 3168x1296 (3072x1280). Sem imagens de origem, a Ideogram também precisa de uma de suas predefinições 1K/2K suportadas, uma lista que não publica, então um tamanho que passa nas verificações ainda pode receber um HTTP 400.

Arquivos Principais

• prompting.md — esquema JSON completo, ordenação estrita de chaves, sistema de coordenadas bbox, regras de paleta
• examples.md — legendas trabalhadas para cartões de título, miniaturas, cartões de citação, CTAs de marca

Adequação para Produção de Vídeo

O nicho do Ideogram 4 no kit de ferramentas são slides e miniaturas com texto embutido, onde FLUX e LTX-2 falham (ambos renderizam texto distorcido). Pares naturais:

Caso de uso	Por que Ideogram 4
Fundo de cartão de título / CTA com texto de título	Texto legível + cores hex exatas da marca em uma passagem
Miniatura do YouTube / redes sociais com uma frase impactante	Texto grande e legível é seu ponto mais forte
Cartão de citação / cartão de estatística	Texto de múltiplas linhas + controle de layout via bboxes
Letreiros/logotipos dentro de uma cena de demonstração de produto	Texto na imagem que outros modelos não conseguem renderizar

Em seguida, alimente a imagem estática no Remotion (<OffthreadVideo>/Img) ou anime-a com tools/ltx2.py --input.