Imagegen

Skill de Geração de Imagens

Gera ou edita imagens para o projeto atual (por exemplo, assets de website, assets de game, mockups de UI, mockups de produto, wireframes, design de logo, imagens fotorrealistas, infográficos). Usa como padrão gpt-image-1.5 e a OpenAI Image API, e prefere o CLI agrupado para execuções determinísticas e reproduzíveis.

Quando usar

• Gerar uma nova imagem (concept art, product shot, capa, hero de website)
• Editar uma imagem existente (inpainting, edições com máscara, transformações de iluminação ou clima, substituição de fundo, remoção de objetos, composição, fundo transparente)
• Execuções em lote (muitos prompts ou muitas variantes entre prompts)

Árvore de decisão (gerar vs editar vs lote)

• Se o usuário fornece uma imagem de entrada (ou diz "edit/retouch/inpaint/mask/translate/localize/change only X") → editar
• Senão, se o usuário precisa de muitos prompts/assets diferentes → generate-batch
• Senão → gerar

Fluxo de trabalho

1. Decida a intenção: gerar vs editar vs lote (veja a árvore de decisão acima).
2. Colete as entradas antecipadamente: prompt(s), texto exato (palavra por palavra), restrições/lista de evitar, e qualquer imagem(ns) de entrada/máscara(s). Para edições de múltiplas imagens, rotule cada entrada por índice e função; para edições, liste invariantes explicitamente.
3. Se lote: escreva um JSONL temporário em tmp/ (um trabalho por linha), execute uma vez e depois delete o JSONL.
4. Aumente o prompt em uma especificação curta rotulada (estrutura + restrições) sem inventar novos requisitos criativos.
5. Execute o CLI agrupado (scripts/image_gen.py) com padrões sensatos (veja references/cli.md).
6. Para edições/gerações complexas, inspecione as saídas (abra/visualize imagens) e valide: assunto, estilo, composição, precisão de texto e invariantes/itens a evitar.
7. Itere: faça uma única mudança direcionada (prompt ou máscara), execute novamente, verifique novamente.
8. Salve/retorne as saídas finais e anote o prompt final + flags utilizados.

Convenções de temp e saída

• Use tmp/imagegen/ para arquivos intermediários (por exemplo, lotes JSONL); delete quando terminar.
• Escreva artefatos finais em output/imagegen/ ao trabalhar neste repositório.
• Use --out ou --out-dir para controlar caminhos de saída; mantenha nomes de arquivo estáveis e descritivos.

Dependências (instale se ausentes)

Prefira uv para gerenciamento de dependências.

Pacotes Python:

uv pip install openai pillow

Se uv não estiver disponível:

python3 -m pip install openai pillow

Ambiente

• OPENAI_API_KEY deve estar definida para chamadas de API ao vivo.

Se a chave estiver ausente, forneça ao usuário estas etapas:

1. Crie uma chave de API na interface da plataforma OpenAI: https://platform.openai.com/api-keys
2. Defina OPENAI_API_KEY como uma variável de ambiente no seu sistema.
3. Ofereça-se para guiá-lo na configuração da variável de ambiente para seu SO/shell, se necessário.

• Nunca peça ao usuário que cole a chave completa no chat. Peça para defini-la localmente e confirme quando estiver pronto.

Se a instalação não for possível neste ambiente, diga ao usuário qual dependência está ausente e como instalá-la localmente.

Padrões e regras

• Use gpt-image-1.5 a menos que o usuário explicitamente solicite gpt-image-1-mini ou explicitamente prefira um modelo mais barato/rápido.
• Assuma que o usuário quer uma nova imagem a menos que explicitamente solicite uma edição.
• Exija OPENAI_API_KEY antes de qualquer chamada de API ao vivo.
• Use o SDK Python da OpenAI (pacote openai) para todas as chamadas de API; não use HTTP bruto.
• Se o usuário solicitar edições, use client.images.edit(...) e inclua imagens de entrada (e máscara se fornecida).
• Prefira o CLI agrupado (scripts/image_gen.py) em vez de escrever novos scripts pontuais.
• Nunca modifique scripts/image_gen.py. Se algo estiver faltando, pergunte ao usuário antes de fazer qualquer coisa.
• Se o resultado não for claramente relevante ou não satisfizer as restrições, itere com pequenas mudanças de prompt direcionadas; apenas faça uma pergunta se um detalhe ausente bloquear o sucesso.

Aumento de prompt

Reformate prompts do usuário em uma especificação estruturada e orientada para produção. Apenas torne explícitos os detalhes implícitos; não invente novos requisitos.

Taxonomia de casos de uso (slugs exatos)

Classifique cada solicitação em um destes buckets e mantenha o slug consistente entre prompts e referências.

Gerar:

• photorealistic-natural — cenas de estilo de vida candid/editorial com textura real e iluminação natural.
• product-mockup — shots de produto/embalagem, imagens de catálogo, conceitos de merch.
• ui-mockup — mockups de interface de app/web que parecem enviáveis.
• infographic-diagram — diagramas/infográficos com layout estruturado e texto.
• logo-brand — exploração de logo/marca, amigável a vetor.
• illustration-story — quadrinhos, arte de livros infantis, cenas narrativas.
• stylized-concept — concept art orientado ao estilo, renders 3D/estilizados.
• historical-scene — cenas com precisão de período/conhecimento de mundo.

Editar:

• text-localization — traduzir/substituir texto em imagem, preservar layout.
• identity-preserve — prova virtual, pessoa em cena; bloquear rosto/corpo/pose.
• precise-object-edit — remover/substituir um elemento específico (incl. trocas interiores).
• lighting-weather — mudanças apenas de hora do dia/estação/atmosfera.
• background-extraction — fundo transparente / recorte limpo.
• style-transfer — aplicar estilo de referência enquanto muda assunto/cena.
• compositing — inserção/fusão de múltiplas imagens com iluminação/perspectiva combinadas.
• sketch-to-render — desenho/arte linear para render fotorrealista.

Esclarecimento rápido (aumento vs invenção):

• Se o usuário diz "uma imagem hero para uma landing page", você pode adicionar restrições de layout/composição que são implícitas nesse uso (por exemplo, "espaço negativo generoso à direita para texto de headline").
• Não introduza novos elementos criativos que o usuário não pediu (por exemplo, adicionar mascote, mudar o assunto, inventar nomes de marca/logos).

Modelo (inclua apenas linhas relevantes):

Caso de uso: <slug de taxonomia>
Tipo de asset: <onde o asset será usado>
Solicitação principal: <prompt principal do usuário>
Cena/fundo: <ambiente>
Assunto: <assunto principal>
Estilo/meio: <foto/ilustração/3D/etc>
Composição/enquadramento: <amplo/close/top-down; posicionamento>
Iluminação/mood: <iluminação + mood>
Paleta de cores: <notas da paleta>
Materiais/texturas: <detalhes de superfícies>
Qualidade: <baixa/média/alta/automática>
Fidelidade de entrada (edições): <baixa/alta>
Texto (palavra por palavra): "<texto exato>"
Restrições: <deve manter/deve evitar>
Evitar: <restrições negativas>

Regras de aumento:

• Mantenha breve; adicione apenas detalhes que o usuário já implícita ou explicitamente forneceu.
• Sempre classifique a solicitação em um slug de taxonomia acima e adeque restrições/composição/qualidade a esse bucket. Use o slug para encontrar o exemplo correspondente em references/sample-prompts.md.
• Se o usuário fizer uma solicitação ampla (por exemplo, "Gere imagens para este website"), use bom senso para propor assets saborosos e apropriados ao contexto e mapeie cada um para um slug de taxonomia.
• Para edições, liste explicitamente invariantes ("mude apenas X; mantenha Y inalterado").
• Se algum detalhe crítico estiver ausente e bloquear o sucesso, faça uma pergunta; senão, prossiga.

Exemplos

Exemplo de geração (imagem hero)

Caso de uso: stylized-concept
Tipo de asset: hero de landing page
Solicitação principal: uma imagem hero minimalista de uma xícara de café de cerâmica
Estilo/meio: fotografia de produto limpa
Composição/enquadramento: produto centralizado, espaço negativo generoso à direita
Iluminação/mood: iluminação de estúdio suave
Restrições: sem logos, sem texto, sem watermark

Exemplo de edição (invariantes)

Caso de uso: precise-object-edit
Tipo de asset: substituição de fundo em foto de produto
Solicitação principal: substituir o fundo por um gradiente de pôr do sol caloroso
Restrições: mude apenas o fundo; mantenha o produto e suas bordas inalterados; sem texto; sem watermark

Melhores práticas de prompting (lista breve)

• Estruture o prompt como cena -> assunto -> detalhes -> restrições.
• Inclua o uso pretendido (anúncio, mock de UI, infográfico) para definir o modo e nível de polimento.
• Use linguagem de câmera/composição para fotorrealismo.
• Cite texto exato e especifique tipografia + posicionamento.
• Para palavras tricky, soletreia letra por letra e exija renderização palavra por palavra.
• Para múltiplas entradas de imagem, referencie imagens por índice e descreva como combiná-las.
• Para edições, repita invariantes em cada iteração para reduzir variação.
• Itere com follow-ups de mudança única.
• Para execuções sensíveis à latência, comece com quality=low; use quality=high para saídas com muito texto ou críticas em detalhes.
• Para edições rigorosas (bloqueio de identidade/layout), considere input_fidelity=high.
• Se os resultados parecerem "tacky", adicione uma breve linha "Evitar:" (vibe de stock photo; cheesy lens flare; neon oversaturado; bloom duro; oversharpening; desordem) e especifique contenção ("editorial", "premium", "subtle").

Mais princípios: references/prompting.md. Especificações copy/paste: references/sample-prompts.md.

Orientação por tipo de asset

Modelos de tipo de asset (assets de website, assets de game, wireframes, logo) são consolidados em references/sample-prompts.md.

Notas de CLI + ambiente

• Comandos CLI + exemplos: references/cli.md
• Quick reference de parâmetro de API: references/image-api.md
• Se as aprovações de rede / configurações de sandbox estão atrapalhando: references/codex-network.md

Mapa de referência

• references/cli.md: como executar geração/edições/lotes de imagens via scripts/image_gen.py (comandos, flags, receitas).
• references/image-api.md: que botões existem no nível de API (parâmetros, tamanhos, qualidade, fundo, campos apenas de edição).
• references/prompting.md: princípios de prompting (estrutura, restrições/invariantes, padrões de iteração).
• references/sample-prompts.md: receitas de prompt copy/paste (fluxos de geração + edição; apenas exemplos).
• references/codex-network.md: ambiente/sandbox/troubleshooting de aprovação de rede.