grahama1970/imagegen

Habilidade de Geração de Imagens

Gera ou edita imagens para o projeto atual (por exemplo, assets de site, assets de jogo, maquetes de UI, maquetes de produto, wireframes, design de logotipo, imagens fotorrealistas ou infográficos).

Modos de nível superior e regras

Esta habilidade possui exatamente dois modos de nível superior:

• Modo de ferramenta embutida padrão (preferido): ferramenta image_gen embutida para geração, edição e solicitações simples de imagens transparentes. Não requer OPENAI_API_KEY.
• Modo CLI de fallback: CLI scripts/image_gen.py. Use quando o usuário solicitar explicitamente o caminho CLI/API/modelo, ou após o usuário confirmar explicitamente um fallback de transparência nativa com gpt-image-1.5. Requer OPENAI_API_KEY.

Dentro do fallback CLI, a CLI expõe três subcomandos:

• generate
• edit
• generate-batch

Regras:

• Use a ferramenta image_gen embutida por padrão para solicitações normais de geração e edição de imagens.
• Não mude para o fallback CLI para controle comum de qualidade, tamanho ou caminho de arquivo.
• Se o usuário solicitar explicitamente uma imagem/fundo transparente, permaneça na image_gen embutida primeiro: solicite um fundo chroma-key plano removível e, em seguida, remova-o localmente com o helper instalado em $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py.
• Nunca mude silenciosamente da image_gen embutida ou CLI gpt-image-2 para CLI gpt-image-1.5. Trate isso como um downgrade de modelo/caminho e pergunte ao usuário antes de fazê-lo, a menos que o usuário já tenha solicitado explicitamente gpt-image-1.5, scripts/image_gen.py ou fallback CLI.
• Se uma solicitação de transparência parecer muito complexa para remoção limpa de chroma-key, o usuário solicitar transparência verdadeira/nativa ou a remoção local falhar na validação, explique que a transparência verdadeira requer CLI gpt-image-1.5 --background transparent --output-format png porque gpt-image-2 não suporta background=transparent, e então pergunte se deseja prosseguir. Execute o fallback CLI somente após o usuário confirmar.
• A palavra batch por si só não significa fallback CLI. Se o usuário solicitar muitos assets ou disser para gerar assets em lote sem solicitar explicitamente controles CLI/API/modelo, permaneça no caminho embutido e emita uma chamada embutida por asset ou variante solicitada.
• Se a ferramenta embutida falhar ou não estiver disponível, informe ao usuário que o fallback CLI existe e que requer OPENAI_API_KEY. Prossiga somente se o usuário solicitar explicitamente esse fallback.
• Se o usuário solicitar explicitamente o modo CLI, use o fluxo de trabalho scripts/image_gen.py incluído. Não crie executores SDK avulsos.
• Nunca modifique scripts/image_gen.py. Se algo estiver faltando, pergunte ao usuário antes de fazer qualquer outra coisa.

Política de caminho de salvamento embutido:

• No modo de ferramenta embutida, o Codex salva as imagens geradas em $CODEX_HOME/* por padrão.
• Não descreva ou dependa de temp do SO como destino embutido padrão.
• Não descreva ou dependa de um argumento de caminho de destino (se houver) na ferramenta image_gen embutida. Se um local específico for necessário, gere primeiro e depois mova ou copie a saída selecionada de $CODEX_HOME/generated_images/....
• Precedência de caminho de salvamento no modo embutido:
  1. Se o usuário nomear um destino, mova ou copie a saída selecionada para lá.
  2. Se a imagem for destinada ao projeto atual, mova ou copie a imagem final selecionada para o workspace antes de finalizar.
  3. Se a imagem for apenas para visualização ou brainstorming, renderize-a inline; o arquivo subjacente pode permanecer no caminho padrão $CODEX_HOME/*.
• Nunca deixe um asset referenciado pelo projeto apenas no caminho padrão $CODEX_HOME/*.
• Não sobrescreva um asset existente a menos que o usuário tenha solicitado explicitamente a substituição; caso contrário, crie um nome de arquivo versionado irmão, como hero-v2.png ou item-icon-edited.png.

Orientações de prompt compartilhadas para ambos os modos estão em references/prompting.md e references/sample-prompts.md.

Documentos/recursos somente para fallback (modo CLI):

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.py

Helper local de pós-processamento:

• $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py: remove um fundo chroma-key plano de uma imagem gerada e escreve um PNG/WebP com alfa. Prefira amostragem automática de chave, matiz suave e despill para bordas anti-serrilhadas.

Quando usar

• Gerar uma nova imagem (arte conceitual, foto de produto, capa, hero de site)
• Gerar uma nova imagem usando uma ou mais imagens de referência para estilo, composição ou clima
• Editar uma imagem existente (inpainting, transformações de iluminação ou clima, substituição de fundo, remoção de objeto, composição, fundo transparente)
• Produzir muitos assets ou variantes para uma tarefa

Quando não usar

• Estender ou corresponder a um conjunto de ícones SVG/vetor existente, sistema de logotipos ou biblioteca de ilustrações dentro do repositório
• Criar formas simples, diagramas, wireframes ou ícones que são melhor produzidos diretamente em SVG, HTML/CSS ou canvas
• Fazer uma pequena edição de asset local do projeto quando o arquivo de origem já existir em um formato nativo editável
• Qualquer tarefa onde o usuário claramente queira saída nativa de código determinística em vez de um bitmap gerado

Árvore de decisão

Pense em duas perguntas separadas:

1. Intenção: é uma nova imagem ou uma edição de uma imagem existente?
2. Estratégia de execução: é um asset ou muitos assets/variantes?

Intenção:

• Se o usuário quiser modificar uma imagem existente preservando partes dela, trate a solicitação como edição.
• Se o usuário fornecer imagens apenas como referências para orientação de estilo, composição, clima ou assunto, trate a solicitação como geração.
• Se o usuário não fornecer imagens, trate a solicitação como geração.

Semântica de edição embutida:

• O modo de edição embutida é para imagens já visíveis no contexto da conversa, como imagens anexadas ou imagens geradas anteriormente no thread.
• Se o usuário quiser editar um arquivo de imagem local com a ferramenta embutida, primeiro carregue-o com a ferramenta view_image embutida para que a imagem fique visível no contexto da conversa e, em seguida, prossiga com o fluxo de edição embutida.
• Não prometa edição arbitrária de caminho de sistema de arquivos através da ferramenta embutida.
• Se um arquivo local ainda precisar de controle direto de caminho de arquivo, máscaras ou outros parâmetros explícitos somente CLI, use o fallback CLI explícito somente quando o usuário solicitar.
• Para edições, preserve invariantes agressivamente e salve de forma não destrutiva por padrão.

Estratégia de execução:

• No caminho padrão embutido, produza muitos assets ou variantes emitindo uma chamada image_gen por asset ou variante solicitada.
• No caminho de fallback CLI, use o subcomando CLI generate-batch somente quando o usuário tiver escolhido explicitamente o modo CLI e precisar de muitos prompts/assets.
• Para muitos assets distintos, não use n como substituto para prompts separados. n é para variantes de um prompt; assets distintos precisam de chamadas embutidas distintas ou trabalhos CLI generate-batch distintos.

Assuma que o usuário quer uma nova imagem, a menos que ele peça claramente para alterar uma existente.

Fluxo de trabalho

1. Decida o modo de nível superior: embutido por padrão, incluindo solicitações simples de saída transparente; fallback CLI somente se solicitado explicitamente ou após o usuário confirmar explicitamente um fallback de saída transparente.
2. Decida a intenção: generate ou edit.
3. Decida se a saída é apenas para visualização ou destinada a ser consumida pelo projeto atual.
4. Decida a estratégia de execução: asset único vs. chamadas embutidas repetidas vs. CLI generate-batch.
5. Colete as entradas antecipadamente: prompt(s), texto exato (literal), restrições/lista de evitação e quaisquer imagens de entrada.
6. Para cada imagem de entrada, rotule seu papel explicitamente:
   • imagem de referência
   • alvo de edição
   • entrada de inserção/estilo/composição de suporte
7. Se o alvo de edição estiver apenas no sistema de arquivos local e você estiver permanecendo no caminho embutido, inspecione-o com view_image primeiro para que a imagem fique disponível no contexto da conversa.
8. Se o usuário solicitou uma foto, ilustração, sprite, imagem de produto, banner ou outro asset explicitamente raster, use image_gen em vez de substituir por placeholders SVG/HTML/CSS. Se a solicitação for para um ícone, logotipo ou gráfico de UI que deva corresponder a assets SVG/vetor/código nativos existentes no repositório, prefira editar esses diretamente.
9. Aumente o prompt com base na especificidade:
   • Se o prompt do usuário já for específico e detalhado, normalize-o em uma especificação clara sem adicionar requisitos criativos.
   • Se o prompt do usuário for genérico, adicione um aumento criterioso somente quando melhorar materialmente a qualidade da saída.
10. Use a ferramenta image_gen embutida por padrão.
11. Para solicitações de saída transparente, siga as orientações de imagem transparente abaixo: gere com a image_gen embutida em um fundo chroma-key plano, copie a saída selecionada para o workspace ou tmp/imagegen/, execute o helper $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py instalado e valide o resultado alfa antes de usá-lo. Se esse caminho parecer inadequado ou falhar, pergunte antes de mudar para CLI gpt-image-1.5.
12. Inspecione as saídas e valide: assunto, estilo, composição, precisão do texto e itens invariantes/evitar.
13. Itere com uma única alteração direcionada e, em seguida, verifique novamente.
14. Para trabalho apenas de visualização, renderize a imagem inline; o arquivo subjacente pode permanecer no caminho padrão $CODEX_HOME/generated_images/....
15. Para trabalho vinculado ao projeto, mova ou copie o artefato selecionado para o workspace e atualize qualquer código ou referências consumidoras. Nunca deixe um asset referenciado pelo projeto apenas no caminho padrão $CODEX_HOME/generated_images/....
16. Para lotes ou solicitações de múltiplos assets, persista cada entregável final solicitado no workspace, a menos que o usuário tenha solicitado explicitamente manter as saídas apenas para visualização. Variantes descartadas não precisam ser mantidas, a menos que solicitado.
17. Se o usuário escolher ou confirmar explicitamente o fallback CLI, use a documentação somente fallback para modelo, qualidade, tamanho, input_fidelity, máscaras, formato de saída, caminhos de saída e configuração de rede.
18. Sempre informe o(s) caminho(s) final(is) salvo(s) para qualquer(ais) asset(s) vinculado(s) ao workspace, mais o prompt final ou conjunto de prompts e se a ferramenta embutida ou o modo CLI de fallback foi usado.

Solicitações de imagem transparente

Solicitações de imagem transparente ainda usam a image_gen embutida primeiro. Como a ferramenta embutida não expõe um controle de fundo transparente verdadeiro, crie uma imagem de origem chroma-key removível e, em seguida, converta a cor da chave para alfa localmente.

Sequência padrão:

1. Use a image_gen embutida para gerar o assunto solicitado em um fundo chroma-key sólido perfeitamente plano.
2. Escolha uma cor de chave que seja improvável de aparecer no assunto: padrão #00ff00, use #ff00ff para assuntos verdes e evite #0000ff para assuntos azuis.
3. Após a geração, mova ou copie a imagem de origem selecionada de $CODEX_HOME/generated_images/... para o workspace ou tmp/imagegen/.
4. Execute o caminho do helper instalado, não um caminho de script relativo ao projeto:

   python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. Valide se a saída tem um canal alfa, cantos transparentes, cobertura de assunto plausível e nenhuma franja óbvia da cor da chave. Se uma franja fina permanecer, tente novamente uma vez com --edge-contract 1; use --edge-feather 0.25 somente quando a borda estiver visivelmente em escada e o assunto não for brilhante ou reflexivo.
6. Salve o PNG/WebP alfa final no projeto se o asset estiver vinculado ao projeto. Nunca deixe um asset transparente referenciado pelo projeto apenas em $CODEX_HOME/*.

Formule solicitações transparentes assim:

Crie o assunto solicitado em um fundo chroma-key #00ff00 sólido perfeitamente plano para remoção de fundo.
O fundo deve ser uma cor uniforme sem sombras, gradientes, textura, reflexos, plano de chão ou variação de iluminação.
Mantenha o assunto completamente separado do fundo com bordas nítidas e espaçamento generoso.
Não use #00ff00 em nenhum lugar do assunto.
Sem sombra projetada, sem sombra de contato, sem reflexo, sem marca d'água e sem texto, a menos que explicitamente solicitado.

Não use automaticamente CLI gpt-image-1.5 --background transparent --output-format png em vez de chroma key. Pergunte ao usuário primeiro quando o usuário solicitar transparência verdadeira/nativa, quando a remoção local falhar na validação ou quando a imagem solicitada for complexa: cabelo, pelo, penas, fumaça, vidro, líquidos, materiais translúcidos, objetos reflexivos, sombras suaves, aterramento de produto realista ou cores de assunto que entrem em conflito com todas as cores de chave práticas.

Use uma confirmação concisa como:

Isso provavelmente precisa de transparência nativa verdadeira. O caminho embutido padrão usa um fundo chroma-key com remoção local, mas a transparência verdadeira requer o fallback CLI com gpt-image-1.5 porque gpt-image-2 não suporta background=transparent. Também requer OPENAI_API_KEY. Devo prosseguir com esse fallback CLI?

Aumento de prompt

Reformate os prompts do usuário em uma especificação estruturada e orientada à produção. Torne o objetivo do usuário mais claro e acionável, mas não adicione detalhes cegamente.

Trate isso como orientação de modelagem de prompt, não um esquema fechado. Use apenas as linhas que ajudam e adicione uma linha extra rotulada curta quando melhorar materialmente a clareza.

Política de especificidade

Use a especificidade do prompt do usuário para decidir quanto aumento é apropriado:

• Se o prompt já for específico e detalhado, preserve essa especificidade e apenas normalize/estruture-o.
• Se o prompt for genérico, você pode adicionar um aumento criterioso quando melhorar materialmente o resultado.

Aumentos permitidos:

• dicas de composição ou enquadramento
• dicas de nível de polimento ou uso pretendido
• orientação prática de layout
• concretude de cena razoável que suporte a solicitação declarada

Aumentos não permitidos:

• personagens ou objetos extras que não são implícitos pela solicitação
• nomes de marcas, slogans, paletas ou batidas narrativas que não são implícitas
• posicionamento arbitrário específico de lado, a menos que o layout circundante o suporte