shijianjizhe/remotion

codex-image

Gere e edite imagens com GPT Image por meio da assinatura ChatGPT do usuário. A saída é salva em ./generated_images/ (ou --out-dir / --out).

Como executar

Tudo passa por um único script. Resolva o diretório absoluto que contém este SKILL.md (seu harness o anuncia quando o skill carrega — abaixo está escrito <skill-dir>), então:

bash "<skill-dir>/scripts/generate.sh" "<prompt>" [flags]

Nunca invoque um caminho relativo simples scripts/generate.sh: seu diretório de trabalho é o projeto do usuário, não o local de instalação do skill (que varia por agente — ~/.claude/skills/, ~/.agents/skills/, ~/.opencode/skills/, um .claude/skills/ local ao projeto, …).

Pré-requisitos que o script verifica para você:

• python3 ≥ 3.10 no PATH (bash + stdlib Python caso contrário).
• Pillow — apenas para --format webp e --transparent-mode chroma. Não instalado por padrão; essas execuções falham rapidamente com o comando de instalação (python3 -m pip install 'Pillow>=10'). --transparent simples não precisa dele. Mencione este pré-requisito antes do primeiro uso de qualquer um deles.
• Codex CLI autenticado. Se não estiver, o script termina com Run: codex login — repasse isso ao usuário em vez de lidar com a autenticação você mesmo.

bash "<skill-dir>/scripts/generate.sh" --help imprime a superfície completa de flags; consulte-a antes de improvisar flags. Quando o agente hospedeiro suporta comandos barra digitados, /codex-image "<prompt>" --flags é uma abreviação voltada ao usuário para exatamente esta chamada de script.

O script é mecânico — ele não faz roteamento semântico. O tratamento de continuação, decisões de lote e despacho de remoção de fundo são SUA responsabilidade, com base na conversa.

GPT Image 2.5

A OpenAI oferece gpt-image-2.5-sunburst para edição precisa e gpt-image-2.5-flare para geração mais rápida no dia a dia. Para solicitar um, passe --image-model <model-id>; omita para manter a seleção padrão do Codex Responses. Esta flag é experimental no transporte de assinatura: verificações ao vivo em 2026-09-08 solicitaram cada variante, mas ambas as respostas relataram gpt-image-2-codex. Não afirme um upgrade 2.5 apenas com base em uma solicitação bem-sucedida. Um alias de resposta legada ou versão C2PA 2.0 também não prova pesos mais antigos: uma imagem publicada no anúncio 2.5 da OpenAI carrega essa mesma versão de proveniência. O script avisa quando o modelo relatado é diferente ou está ausente; inspecione o image_model do sidecar separadamente de requested_image_model. --orchestrator seleciona o modelo principal que chama a ferramenta de imagem, não Sunburst ou Flare. Deixe-o de fora: o script usa o modelo Sol-tier mais recente (gpt-<version>-sol) que a conta lista, para que um modelo aposentado nunca o quebre. As requisições vão para onde a própria configuração do Codex envia o Codex: um model_provider personalizado, como um proxy, um openai_base_url relay, ou chatgpt.com.

Leia Compatibilidade GPT Image 2.5 para comportamento de transporte verificado e as fontes oficiais. O suporte da API pública para seleção de modelo, xhigh/max, e transparência não estabelece o mesmo comportamento no Codex Responses.

Tratamento de continuação

Quando a solicitação modifica a imagem gerada no turno imediatamente anterior ("escureça", "agora adicione um chapéu", "mais contraste"), passe --from-last — o script reutiliza a última geração automaticamente (rastreada em ~/.codex-image/last.json), então você não precisa recuperar o caminho da transcrição.

Para edições em um arquivo explícito ou uma geração mais antiga, passe --input <caminho|url> (repetível; máximo de 16 referências combinadas com --from-last; o limite de referências do skill).

Quando a solicitação é um assunto novo — mesmo que expressa como "agora faça…" — não passe nenhum e gere do zero. Se você errar e o usuário disser "não, eu quis dizer um novo", execute novamente sem referências.

Imagens que o usuário fornece apenas para estilo, composição ou clima são referências para uma geração, não alvos de edição — passe-as via --input, mas formule o prompt como uma nova imagem ("no estilo da Imagem 2"). Ao misturar várias entradas, rotule cada uma pelo índice e função no prompt (Imagem 1: alvo de edição, Imagem 2: referência de estilo).

Após gerar: veja, depois relate

Antes de dizer ao usuário que você terminou, visualize o arquivo de imagem salvo e verifique se está de acordo com a solicitação: assunto, composição, qualquer texto literal renderizado literalmente, e todas as restrições que o usuário declarou. Se algo estiver errado, itere com UMA alteração direcionada (via --from-last), reafirmando os invariantes que não devem se desviar. Não acumule várias correções em uma única reexecução, e não relate um caminho que você não tenha visualizado.

Disciplina de salvamento: a saída padrão é ./generated_images/. Se a imagem for destinada ao projeto do usuário, copie ou mova-a para seu lugar real (e atualize qualquer código que a referencie) — não deixe um ativo do projeto apenas no diretório temporário. Nunca sobrescreva um ativo existente que o usuário não pediu para substituir; escreva um irmão versionado (hero-v2.png).

Imagens transparentes

Quando o usuário quiser um fundo transparente, adicione --transparent. Só isso — nenhuma decisão de despacho, nenhum Pillow, nenhuma etapa de pós-processamento para você orquestrar.

O script pede alfa diretamente ao modelo: ele envia background: "auto" e acrescenta uma frase ao prompt, e o backend retorna RGBA. Não passe --background transparent; esse valor é rejeitado por este backend (docs/adr/0001-request-transparency-in-the-prompt.md explica por quê, e por que a "correção" óbvia está errada).

Se você testar o backend e vir "Transparent background is not supported for this model.", não conclua que a transparência não está disponível. Esse 400 é a recusa do parâmetro, não da capacidade. O modelo retorna alfa real quando solicitado no prompt, que é o que --transparent faz. Conselhos de que a transparência nativa precisa de gpt-image-1.5 ou uma OPENAI_API_KEY são pré-0.2.0 e estão errados; se você os está lendo, seu skill instalado está desatualizado. Verifique metadata.version neste arquivo — deve ser 0.2.0 ou posterior.

Duas coisas a acertar ao escrever o prompt:

• Descreva o assunto, não uma cena. Prompt supera parâmetro. "Uma caneca em uma mesa de madeira em um estúdio iluminado pelo sol" pode renderizar esse estúdio em vez de isolar a caneca. Nomeie o assunto e seu material; deixe o ambiente de fora.
• Não adicione suas próprias proibições. O sufixo deliberadamente não proíbe nada. Se o usuário pediu uma sombra projetada, deixe-o tê-la — ela volta renderizada no alfa e se compõe corretamente. Adicionar "sem sombra, sem fundo" por conta própria substitui a intenção deles.

Após gerar, visualize o arquivo e verifique se o alfa realmente chegou. O script avisa no stderr quando o resultado não tem alfa ou é totalmente opaco; trate isso como um sinal para reexecutar com UMA alteração direcionada, geralmente removendo linguagem de cena.

Escada de fallback, apenas quando o nativo decepciona (verificado em assuntos opacos; cabelo, vidro, fumaça e translucidez não foram testados):

Escalonamento	Ação
Re-prompt	Remova linguagem de cena/fundo, nomeie o assunto sozinho
Aumentar qualidade	--quality medium para bordas finas e texto pequeno
Chroma	--transparent-mode chroma (precisa de Pillow) — você controla a placa-chave
Adobe MCP	--transparent-mode chroma --bg-tool=none, depois chame qualquer ferramenta de remoção de fundo Adobe que esta sessão expor (procure por uma ferramenta MCP cujo nome contenha remove_background) e sobrescreva o arquivo com o resultado alfa. Melhor opção para translucidez

Reparo de borda cromática: franja fina → --edge-contract 1; bordas em escada em assuntos foscas → --edge-feather 0.25. Modos de falha mais profundos: references/transparent-image-tips.md.

Qualidade, custo e limites de tempo

• O padrão é --quality high; low, medium, high, xhigh, max e auto são solicitações aceitas. Comece com low para rascunhos. Codex Responses pode substituir a qualidade; inspecione resolved_quality no sidecar ou na saída --verbose antes de reivindicar que um nível foi entregue.
• As gerações contam contra os limites do plano ChatGPT do usuário. A latência varia conforme o modelo, prompt, qualidade e carga do serviço.
• Antes de gerar mais de 3 imagens para uma única solicitação, confirme primeiro com o usuário.
• Nunca faça loop infinito. "Muitas" / "um conjunto inteiro" → escolha um padrão sensato (4) e ofereça continuar.
• HTTP 429 do backend = pare imediatamente, não tente novamente.

Fluxos de trabalho comuns

# Geração única
bash "<skill-dir>/scripts/generate.sh" "um táxi amarelo à noite na chuva"

# Continuação da geração anterior
bash "<skill-dir>/scripts/generate.sh" "agora adicione vapor subindo" --from-last

# Editar uma imagem de referência explícita
bash "<skill-dir>/scripts/generate.sh" "deixe-a azul" --input ./caneca.png

# Fundo transparente (alfa nativo do modelo; sem Pillow)
bash "<skill-dir>/scripts/generate.sh" "uma caneca de café" --transparent

# Transparente, com uma sombra que o usuário pediu (sobrevive no alfa)
bash "<skill-dir>/scripts/generate.sh" "uma caneca de café com uma sombra projetada suave" --transparent

# Fallback cromático, quando o nativo decepciona (precisa de Pillow)
bash "<skill-dir>/scripts/generate.sh" "um pote de vidro" --transparent --transparent-mode chroma

# Tamanho / formato / qualidade diferentes
bash "<skill-dir>/scripts/generate.sh" "banner hero" --size 2048x1152 --format webp --quality low

Redação de tokens (segurança)

NUNCA imprima ou registre o access_token, id_token, refresh_token do usuário, ou qualquer cabeçalho Authorization: Bearer .... Os módulos Python do skill redigem automaticamente; você não deve desfazer isso lendo ~/.codex/auth.json você mesmo ou ecoando tokens em mensagens de erro.

Quando NÃO invocar

• Arte vetorial, SVG, arte ASCII ou diagramas LaTeX → use uma ferramenta dedicada de vetores ou diagramas.
• O usuário explicitamente quer um modelo ou produto diferente (DALL-E, Stable Diffusion, Midjourney) → delegue a ele.

Para trabalho de logotipo/marca de produção, invoque — mas defina expectativas: gere explorações e refine com iterações de alteração única --from-last em vez de prometer um ativo final em uma única tentativa (modelos em references/prompting-cookbook.md).

Referências

Quando precisar de mais profundidade, leia de <skill-dir>/references/:

• api-recipe.md — corpo de requisição canônico, cabeçalhos, campos rejeitados, mecanismo de transparência, análise SSE
• prompting-cookbook.md — fundamentos de prompting + modelos de caso de uso (logotipo, foto de produto, mockup de UI, infográfico)
• transparent-image-tips.md — como a transparência nativa funciona, quando ela luta e o fallback cromático

Contexto de nível de repositório: CONTEXT.md (glossário — os três transportes são definidos lá) e docs/adr/ (por que a transparência é solicitada no prompt em vez do parâmetro).