imagegen

Habilidade de Geração de Imagens

Gera ou edita imagens para o projeto atual (por exemplo, assets de sites, assets de jogos, maquetes de UI, maquetes de produtos, wireframes, design de logotipos, imagens fotorrealistas ou infográficos).

Modos e regras principais

Esta habilidade tem exatamente dois modos principais:

• Modo de ferramenta interna padrão (preferido): ferramenta interna image_gen para geração, edição e solicitações simples de imagens com fundo transparente. Não requer OPENAI_API_KEY.
• Modo CLI de fallback: CLI scripts/image_gen.py. Use quando o usuário explicitamente pedir 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.

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

• generate
• edit
• generate-batch

Regras:

• Use a ferramenta interna image_gen por padrão para solicitações normais de geração e edição de imagens.
• Não mude para o CLI fallback por controle comum de qualidade, tamanho ou caminho de arquivo.
• Se o usuário explicitamente pedir uma imagem/fundo transparente, permaneça na ferramenta interna image_gen primeiro: solicite um fundo croma-key plano e removível, depois remova-o localmente com o auxiliar instalado em $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py.
• Nunca mude silenciosamente da ferramenta interna image_gen ou do CLI gpt-image-2 para o 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 CLI fallback.
• Se uma solicitação transparente parecer muito complexa para remoção limpa de croma-key, pedir transparência nativa/verdadeira, ou a remoção local falhar na validação, explique que a transparência verdadeira requer o CLI gpt-image-1.5 --background transparent --output-format png porque gpt-image-2 não suporta background=transparent, então pergunte se deve prosseguir. Execute o CLI fallback apenas após a confirmação do usuário.
• A palavra batch por si só não significa CLI fallback. Se o usuário pedir muitos assets ou disser para gerar assets em lote sem pedir explicitamente controles CLI/API/modelo, permaneça no caminho interno e emita uma chamada interna por asset ou variante solicitada.
• Se a ferramenta interna falhar ou estiver indisponível, informe ao usuário que o CLI fallback existe e que requer OPENAI_API_KEY. Prossiga apenas 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 incluso. Não crie runners 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 interno:

• No modo de ferramenta interna, a Codex salva as imagens geradas em $CODEX_HOME/* por padrão.
• Não descreva nem dependa do temp do SO como destino interno padrão.
• Não descreva nem dependa de um argumento de caminho de destino (se houver) na ferramenta interna image_gen. 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 interno:
  1. Se o usuário nomear um destino, mova ou copie a saída selecionada para lá.
  2. Se a imagem é para o projeto atual, mova ou copie a imagem final selecionada para o workspace antes de finalizar.
  3. Se a imagem é apenas para pré-visualização ou brainstorming, renderize-a inline; o arquivo subjacente pode permanecer no caminho padrão $CODEX_HOME/*.
• Nunca deixe um asset referenciado no projeto apenas no caminho padrão $CODEX_HOME/*.
• Não sobrescreva um asset existente a menos que o usuário tenha explicitamente pedido substituição; caso contrário, crie um nome de arquivo versionado irmão, como hero-v2.png ou item-icon-edited.png.

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

Documentos/recursos apenas de fallback para o modo CLI:

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

Auxiliar de pós-processamento local:

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

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 objetos, composição, fundo transparente)
• Produzir muitos assets ou variantes para uma tarefa

Quando não usar

• Estender ou combinar um conjunto de ícones SVG/vector, sistema de logotipos ou biblioteca de ilustrações existente 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á existe em um formato nativo editável
• Qualquer tarefa onde o usuário claramente quer saída de código nativa determinística em vez de um bitmap gerado

Árvore de decisão

Pense em duas perguntas separadas:

1. Intenção: é uma imagem nova 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 quer modificar uma imagem existente preservando partes dela, trate a solicitação como edição.
• Se o usuário fornece imagens apenas como referências para estilo, composição, clima ou orientação de assunto, trate a solicitação como geração.
• Se o usuário não fornece imagens, trate a solicitação como geração.

Semântica de edição interna:

• O modo de edição interno é 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 interna, primeiro carregue-o com a ferramenta interna view_image para que a imagem fique visível no contexto da conversa, depois prossiga com o fluxo de edição interno.
• Não prometa edição arbitrária de caminho de sistema de arquivos através da ferramenta interna.
• Se um arquivo local ainda precisar de controle direto de caminho de arquivo, máscaras ou outros parâmetros explícitos apenas do CLI, use o fallback CLI explícito somente quando o usuário pedir.
• Para edições, preserve invariantes de forma agressiva e salve de forma não destrutiva por padrão.

Estratégia de execução:

• No caminho interno padrão, produza muitos assets ou variantes emitindo uma chamada image_gen por asset ou variante solicitada.
• No caminho CLI de fallback, use o subcomando CLI generate-batch apenas quando o usuário escolheu explicitamente o modo CLI e precisa 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 internas distintas ou jobs CLI generate-batch distintos.

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

Fluxo de trabalho

1. Decida o modo principal: interno por padrão, incluindo solicitações simples de saída transparente; fallback CLI apenas se explicitamente solicitado 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 pré-visualização ou destinada a ser consumida pelo projeto atual.
4. Decida a estratégia de execução: asset único vs chamadas internas repetidas vs CLI generate-batch.
5. Colete as entradas antecipadamente: prompt(s), texto exato (verbatim), 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 interno, inspecione-o com view_image primeiro para que a imagem esteja disponível no contexto da conversa.
8. Se o usuário pediu 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 deve corresponder a assets SVG/vector/código nativos do repositório existentes, prefira editar esses diretamente.
9. Aumente o prompt com base na especificidade:
   • Se o prompt do usuário já é específico e detalhado, normalize-o em uma especificação clara sem adicionar requisitos criativos.
   • Se o prompt do usuário é genérico, adicione aumento criterioso apenas quando melhorar materialmente a qualidade da saída.
10. Use a ferramenta interna image_gen por padrão.
11. Para solicitações de saída transparente, siga a orientação de imagem transparente abaixo: gere com a ferramenta interna image_gen em um fundo croma-key plano, copie a saída selecionada para o workspace ou tmp/imagegen/, execute o auxiliar instalado $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py e valide o resultado alfa antes de usá-lo. Se este caminho parecer inadequado ou falhar, pergunte antes de mudar para o CLI gpt-image-1.5.
12. Inspecione as saídas e valide: assunto, estilo, composição, precisão do texto e itens invariantes/evitados.
13. Itere com uma única alteração direcionada e depois verifique novamente.
14. Para trabalho apenas de pré-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 no projeto apenas no caminho padrão $CODEX_HOME/generated_images/....
16. Para lotes ou solicitações multi-asset, persista cada entrega final solicitada no workspace, a menos que o usuário tenha explicitamente pedido para manter as saídas apenas como pré-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 então a documentação apenas de fallback para modelo, qualidade, tamanho, input_fidelity, máscaras, formato de saída, caminhos de saída e configuração de rede.
18. Sempre relate o(s) caminho(s) final(is) salvo(s) para qualquer asset vinculado ao workspace, além do prompt final ou conjunto de prompts e se o modo ferramenta interna ou CLI fallback foi usado.

Solicitações de imagem transparente

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

Sequência padrão:

1. Use a ferramenta interna image_gen para gerar o assunto solicitado em um fundo croma-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 auxiliar 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 que a saída tem um canal alfa, cantos transparentes, cobertura plausível do assunto e nenhuma franja de cor-chave óbvia. Se uma franja fina permanecer, tente novamente uma vez com --edge-contract 1; use --edge-feather 0.25 apenas quando a borda estiver visivelmente serrilhada 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 no projeto apenas sob $CODEX_HOME/*.

Solicite solicitações transparentes assim:

Crie o assunto solicitado em um fundo croma-key #00ff00 sólido perfeitamente plano para remoção de fundo.
O fundo deve ser de uma cor uniforme, sem sombras, gradientes, textura, reflexos, plano de chão ou variação de iluminação.
Mantenha o assunto totalmente separado do fundo, com bordas nítidas e preenchimento 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 o CLI gpt-image-1.5 --background transparent --output-format png em vez de croma-key. Pergunte ao usuário primeiro quando o usuário pedir transparência nativa/verdadeira, 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 realista de produto ou cores de assunto que entram 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 interno padrão usa um fundo croma-key mais 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 curta e rotulada 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 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 razoável de cena 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 lateral arbitrário, a menos que o layout ao redor o suporte

Use-ca

…

[truncado para tradução]