shaharsha/image-generation

Geração de Imagens

Duas famílias de modelos, três tarefas.

Modelos cobertos

ID do Modelo	Família	Uso para	Custo (1024×1536, medido em 02/10/2026)
gpt-image-2.5-sunburst	OpenAI (Imagens 2.5, 08/09/2026)	Padrão. Qualquer coisa que pode ser enviada. #1 em todos os principais leaderboards (geração, edição, renderização de texto, retratos)	max ≈ $0,165, ~90 s · high ≈ $0,041, ~35 s
gpt-image-2.5-flare	OpenAI (Imagens 2.5)	Rascunhos rápidos — explorando direções, testando um prompt. Mesmos prompts que Sunburst, ~2× mais rápido	medium ≈ $0,01, ~15 s
gemini-3-pro-image	Google (Nano Banana Pro)	Close-ups de pele/cabelo natural quando votos e revisores discordam; até 14 referências	$0,134 (1K/2K) · $0,24 (4K)
gemini-3.1-flash-image	Google (Nano Banana 2)	Proporções de aspecto extremas (1:4…8:1), fundamentação de pesquisa de imagem	$0,067 (1K)
gemini-3.1-flash-lite-image	Google (Nano Banana 2 Lite)	Exploração Gemini mais barata; apenas 1K, retorna JPEG	$0,034

gpt-image-2 ainda funciona (não obsoleto), mas está um degrau abaixo dos dois modelos 2.5. Os IDs *-preview do Gemini e todos os modelos Imagen estão desligados — os scripts os recusam.

As três tarefas desta skill

1. Escolher o modelo e a qualidade para o ativo. Veja reference/model-selection.md.
2. Escrever o prompt seguindo as regras específicas do modelo. Os dois provedores querem coisas opostas:
   • OpenAI GPT Image 2.5 quer seções rotuladas (cena / assunto / detalhes / restrições), texto exato entre aspas e aceita exclusões inline ("sem texto extra, sem marcas d'água"). Leia reference/openai-gpt-image.md.
   • Gemini quer parágrafos narrativos, frases negativas saem pela culatra (reescreva "sem pessoas" como "rua vazia"), a proporção de aspecto vai em imageConfig. Leia reference/gemini-image.md.
3. Executar a API através dos scripts fornecidos. Veja scripts/README.md.

Qualidade no 2.5 — a armadilha

A escada de qualidade do 2.5 foi recortada. No mesmo tamanho, high do 2.5 compra aproximadamente os tokens de saída de medium do gpt-image-2; max do 2.5 compra o que high do gpt-image-2 fazia (medido: Sunburst 1024×1536 high = 1.372 tokens de saída, max = 5.488). Copiar "quality=high" de velhos hábitos envia silenciosamente uma imagem de detalhamento médio.

Promova rascunhos com uma edição, não com um novo sorteio. Cada nova geração cria uma imagem diferente, então reexecutar o prompt de um rascunho aprovado em max lhe dá uma imagem diferente. Em vez disso, passe o rascunho escolhido como referência para uma edição Sunburst max que altere apenas a qualidade de renderização e preserve todo o resto. Verificado em 02/10/2026: um pôster Flare medium promovido desta forma manteve sua composição, pessoas, poses, cores e texto em hebraico, e ganhou textura e detalhe ($0,18, 85 s).

Estágio	Modelo + qualidade	Por quê
Explorar direções, testar um prompt	Flare medium (--draft)	~1¢ e ~15 s, então 6 direções custam menos que uma final
Promover o rascunho escolhido	Edição Sunburst max com --ref <rascunho> e o prompt de promoção em reference/openai-gpt-image.md	Mantém a aparência que o usuário escolheu, adiciona detalhamento completo
Um final direto de um prompt travado	Sunburst max (padrão do script)	Detalhamento completo; ~90 s, ~$0,17
Sunburst quando o tempo importa mais que o detalhe fino	Sunburst high	Um quarto dos tokens, ~35 s

Nunca use auto — ele cai em orçamentos diferentes para chamadas idênticas.

Seleção de modelo padrão — a regra dos 30 segundos

Explorando direções / "algumas opções rápidas" / testando se um prompt funciona?
  SIM → Flare medium (--draft). Promova a escolha do usuário com uma edição Sunburst max (--ref <rascunho>).
  NÃO  ↓

Close-up fotorealista de rosto humano onde a textura da pele é o ponto?
  SIM → Sunburst max primeiro (lidera os votos de retratos); se a pele parecer muito nítida no zoom,
        compare com gemini-3-pro-image 4K e deixe o humano escolher.
  NÃO  ↓

Banner ultra-largo/alto além de 3:1 (1:4, 4:1, 1:8, 8:1)?
  SIM → gemini-3.1-flash-image (GPT Image limita a 3:1).
  NÃO  ↓

Todo o resto → Sunburst com qualidade=max.
  └── PNG transparente? Nativo: --background transparent (png/webp). Não precisa de rembg.

Árvore de decisão completa por tipo de ativo: reference/model-selection.md.

Fluxo de trabalho por solicitação

1. Confirmar escopo. Tipo de ativo, contexto de marca, direção de cor/estilo, proporção de aspecto alvo + tamanho, onde salvar. Se a solicitação já disser, prossiga.
2. Escolher modelo e qualidade. Use a regra acima; explique a escolha em uma frase.
3. Ler a referência específica do modelo — reference/openai-gpt-image.md ou reference/gemini-image.md. Não escreva de memória: os dois provedores querem estruturas de prompt opostas, e as diretrizes 2.5 mudaram vários hábitos do gpt-image-2.
4. Fundo transparente? No GPT Image 2.5 é nativo. Leia reference/transparent-backgrounds.md apenas para saídas Gemini ou para recortar uma imagem existente.
5. Abrir o template correspondente em templates/ e preencher os placeholders.
6. Texto em hebraico ou RTL na imagem? Leia reference/hebrew-rtl.md primeiro.
7. Mostrar o prompt ao usuário antes de chamar a API a menos que ele tenha dito "apenas faça". Uma revisão de prompt evita a maioria das regenerações caras.
8. Executar o script. Salve em ./generated-images/<nome-descritivo>.png no diretório de trabalho atual, a menos que instruído de outra forma. O script OpenAI imprime latência, tokens de saída e custo por chamada — mantenha o total acumulado.
9. Ler a imagem salva com a ferramenta Read — Claude é multimodal e verá os pixels. Critique contra o briefing: composição, texto escrito exatamente como citado e aparecendo uma vez, cores, defeitos (letras distorcidas, dedos extras, geometria quebrada, granulado em áreas lisas). Identifique problemas antes que o usuário precise.
10. Mostrar ao usuário. open <caminho>, resuma o que você vê (bom e ruim) e proponha enviar / iterar com uma alteração específica / reescrever.

Templates por tipo de ativo

Ativo	Template
Logotipo de marca / marca / marca nominativa	templates/logo.md
Conjunto de ícones (estilo consistente entre ícones)	templates/icon-set.md
Tela de UI de aplicativo móvel	templates/ui-mobile.md
Dashboard web / UI SaaS	templates/ui-dashboard.md
Imagem de herói de marketing / banner	templates/hero-image.md
Foto de produto / hero shot	templates/product-shot.md

Para exemplos práticos literais, veja examples.md.

Personagens recorrentes e storyboards

Para quadrinhos, storyboards e episódios animados onde as mesmas pessoas aparecem em muitas imagens:

• Personagens a partir de fotos. Nunca passe fotos inteiras como referências: o endpoint de edição reestiliza a foto (copia pose, roupas e fundo, adiciona texto de legenda) em vez de desenhar a pessoa. O pipeline funcional:

  1. Recorte os rostos primeiro: python3 <this-skill-dir>/scripts/crop_faces.py photos/ faces/ --sheet faces/_sheet.jpg.
  2. Faça um rosto anime a partir dos recortes.
  3. Edite esse rosto em um cartão de figurino de corpo inteiro, declarando o tipo de corpo.
  4. Obtenha aprovação humana, depois promova.

  Prompts e o loop de revisão: reference/characters-from-photos.md.

• Cenas com 2+ personagens.

  • Rascunho com Sunburst high, não Flare: Flare desenhou apenas Imagem 1, ao ar livre, com legendas.
  • Vincule cada nome ao seu cartão na primeira menção: "Dana (a mulher da Imagem 1)".
  • Proíba legendas em qualquer idioma.
  • Telas de telefone e tablet renderizam por trás: gere o conteúdo da tela como sua própria imagem e componha.

  Receita: reference/multi-character-scenes.md.

• Faturamento em lote. credit_balance_exhausted significa que a conta OpenAI está sem crédito, não uma requisição inválida. Pare, liste quais imagens foram concluídas e, após a recarga, execute novamente apenas as faltantes.

Chaves de API e dependências

Chaves de API vêm de variáveis de ambiente, definidas a partir do seu próprio cofre de segredos no shell que executa o script (cada novo shell precisa delas novamente):

• OPENAI_IMAGE_API_KEY para scripts/openai-image.sh
• GEMINI_IMAGE_API_KEY (ou GEMINI_API_KEY) para scripts/gemini-image.sh; a mesma chave do Google AI Studio também funciona para gerar-clipes-de-vídeo

Essas chaves têm escopo de geração de imagem. Não as reutilize para chat ou embeddings, e nunca as imprima — carregue-as em uma variável, não use echo.

Ferramentas locais (apenas para recortar saídas Gemini ou imagens existentes): rembg (pip install "rembg[cli]" onnxruntime), opcionalmente ImageMagick.

Convenção de saída

• Local de salvamento padrão: ./generated-images/<nome-descritivo>.png no diretório de trabalho atual.
• Nome do arquivo: kebab-case descritivo (logo-agentleh-monocromatico-v1.png); rascunhos recebem -rascunho-N (logo-agentleh-rascunho-3.png).
• Versionamento: anexe -v1, -v2, … ao iterar. Nunca sobrescreva uma geração anterior sem perguntar.
• Saídas transparentes: anexe -transparent após a versão.
• open <caminho> no macOS para mostrar ao usuário logo após a geração.

Padrões de iteração — loop autônomo "iterar até ficar perfeito"

O trabalho do agente é levar a imagem a "boa o suficiente para enviar" antes de perguntar ao usuário:

1. Gerar (chamada do script)
2. Ler o arquivo salvo com a ferramenta Read — Claude VÊ os pixels
3. Auto-crítica contra o briefing:
   - Composição funcionou? (posicionamento, enquadramento, equilíbrio, hierarquia, espaço negativo)
   - Texto escrito exatamente como citado, cada string aparecendo uma vez, legível?
   - Cores certas? (correspondência hex, adesão à paleta)
   - Defeitos? (letras distorcidas, dedos extras, geometria quebrada, granulado em céus/fundos)
   - Briefing realmente satisfeito?
4. Decidir:
   - ENVIAR    → atende ao briefing; mostre ao usuário
   - EDITAR    → uma correção localizada; edite com --ref <anterior> e um prompt que diga
               "mude apenas X" e REESTABELEÇA cada correção anterior e detalhe preservado
   - REESCREVER → problema fundamental de prompt; reescreva do zero, não ajuste
5. Parar quando: 5 iterações usadas, ou $3 gastos neste ativo (some as linhas de custo do script),
   ou estiver pronto para envio.

O usuário é o juiz final — mas Claude é o primeiro juiz. Não mostre um resultado falho e pergunte "está bom?" Mostre-o depois que você verificou que atende ao briefing, ou com sua crítica anexada ("o kerning da marca nominativa está desalinhado; corrigindo no próximo").

Mecânicas por modelo

• Edições GPT Image 2.5 vão por /v1/images/edits via scripts/openai-image.sh --ref <imagem> (até 16 referências). Sem uma máscara, toda a tela é regenerada a cada turno, então deriva se acumula — reestabeleça cada alteração anterior e cada detalhe preservado em cada turno, não apenas o novo pedido. Se uma região deve permanecer pixel-idêntica, componha a edição aprovada no original em vez de esperar que o prompt a segure.
• Edição multi-turno Gemini: scripts/gemini-image.sh --ref <saída-anterior> --prompt "mude X, mantenha Y", sempre terminando com "Mantenha todo o resto na imagem exatamente igual — composição, iluminação, cores, todos os outros elementos."
• Disciplina de deriva. Após 3 iterações malsucedidas na mesma imagem, mude de estratégia: reescreva o prompt base ou mude de modelo.

Preços

GPT Image 2, 2.5 Flare e 2.5 Sunburst compartilham taxas de tokens ($30/1M de saída de imagem, $8/1M de entrada de imagem, $5/1M de entrada de texto; Batch API as reduz pela metade), mas os tokens por imagem diferem por qualidade, tamanho e modelo — então leia o custo que o script imprime em vez de presumir. Gemini é precificado por imagem. Tabela completa e cenários práticos: reference/pricing.md.

Hebraico / RTL

Sunburst e Flare renderizaram corretamente um título em hebraico em um teste de 02/10/2026 (letras certas, ordem certa, direção certa, junto com inglês e um crachá). Tente renderização direta primeiro; recorra ao fluxo de trabalho de composição para linhas longas de hebraico ou uma tipografia licenciada necessária. Hebraico não está na lista de idiomas de melhor desempenho do Google para modelos de imagem Gemini — prefira GPT Image para texto em hebraico. Veja reference/hebrew-rtl.md.

Quando NÃO usar esta skill

• O usuário quer arquivos vetoriais editáveis (SVG com paths). Estes modelos geram rasters; use a skill brand-assets, ou Recraft V4.1 Vector (recraftv4_1_vector, SVG nativo, não integrado nestes scripts).
• O usuário quer dimensões exatas de pixel fora dos tamanhos suportados (ex.: 1200×630). Gere na proporção de aspecto suportada mais próxima, depois corte/redimensione.
• O usuário quer uma foto do mundo real de uma pessoa real específica. Ambos os provedores recusam ou produzem semelhanças imprecisas, e há questões de política.
• O usuário quer "arte de IA" genérica sem um briefing de design — aponte-o para ChatGPT ou o aplicativo Gemini; esta skill é ajustada para trabalho de design.