/gerar-imagem: do Claude Code ao Codex, com o arquivo na sua pasta

O princípio

O Codex CLI tem a ferramenta integrada image_gen.imagegen, ligada pela flag --enable image_generation. Ela roda dentro dos limites da assinatura do Codex, sem OPENAI_API_KEY e sem cobrança por imagem.

Duas coisas quebram a ponte se você não souber:

1. A imagem não nasce na pasta do projeto. Ela cai sempre em ~/.codex/generated_images/<thread-id>/exec-<uuid>.png. A ferramenta não aceita caminho de destino.
2. O --json não devolve o caminho. Nenhum evento do JSONL cita o arquivo. Pedir ao Codex para copiar funciona, mas depende dele obedecer.

Por isso quem manda no destino é o gerar_imagem.py: ele lê o thread_id que o Codex anuncia no --json e copia só os PNGs da pasta daquele thread. Determinístico até com várias gerações ao mesmo tempo.

Antes da primeira vez

Confira o LEIA-ME.txt que veio junto. Sem o Codex CLI instalado e logado, o script não gera nada. Teste rápido no terminal:

codex --version

Quando não usar

• Card, carrossel, story, capa com texto. Texto é camada de HTML ou de editor. A imagem gerada entra como fundo ou como objeto, nunca com a frase dentro. Modelo de imagem erra letra, e erra em português com acento.
• Logo ou símbolo de marca. Símbolo é vetor (SVG), desenhado uma vez e reaproveitado. Gerar por IA devolve um desenho diferente a cada rodada.
• Rosto de pessoa real. Não gerar.

A sequência

1. Travar o briefing. Uma frase de assunto, uma de direção visual (luz, fundo, enquadramento), uma de proibição. Sem isso a imagem sai genérica.

2. Resolver o destino. Pelo contexto da conversa, não perguntando de novo. Sai do config.json (destino_padrao ou um apelido em projetos), ou de --saida com o caminho na mão.

3. Rodar.

python "CAMINHO\DA\SKILL\gerar_imagem.py" "objeto único sobre fundo escuro, luz lateral dura, sombra longa" --nome cofre-vazio --abrir

Sem --saida nem --projeto, cai no destino_padrao do config.json; sem config, na pasta atual.

O script imprime JSON com os caminhos finais. Mostre o caminho e abra a imagem.

4. Olhar a imagem antes de entregar. Leia o PNG. Mão com seis dedos, texto inventado no fundo, rosto onde não podia. Tudo isso passa se ninguém abrir.

Como escrever um briefing que funciona

O modelo responde a substantivo concreto e a descrição de luz. Não responde bem a adjetivo de sentimento.

• Fraco: "uma imagem bonita e moderna sobre organização"
• Forte: "uma única gaveta de arquivo de metal aberta, fundo cinza chapado, luz lateral dura vindo da esquerda, sombra longa, sem texto, sem pessoas"

Diga o que não pode aparecer. É a parte que mais salva tempo.

O que a ferramenta não faz

• Não aceita tamanho nem proporção. O contrato é só prompt, referenced_image_paths e num_last_images_to_include. O modelo decide pelo texto: "objeto centralizado" saiu 1254×1254, "close de três quartos" saiu 1402×1122. Descrever o enquadramento influencia, não garante. Formato final é recorte depois, no Pillow, no Canva ou em qualquer editor.
• Não aceita mais de 1 imagem por chamada da ferramenta. --variacoes resolve pedindo várias chamadas dentro da mesma sessão.
• Não tem seed. Duas rodadas do mesmo prompt dão imagens diferentes.

Custo e tempo

Cada geração leva de 1 a 3 minutos e gasta cerca de 30 mil tokens da assinatura do Codex. Não é grátis em contexto: é grátis em dinheiro. Para lote grande, avise antes do tempo que vai levar.

Existe um caminho de API (scripts/image_gen.py do Codex, modelos gpt-image-2 e gpt-image-1.5). Ele exige OPENAI_API_KEY e cobra por imagem. Não usar sem pedido explícito.

Gotchas apurados

• O Codex pode reclamar Exceeded skills context budget ao iniciar, quando há muitas skills instaladas. É ruído, não erro: a geração acontece do mesmo jeito.
• codex no Windows é um .cmd. O script chama por cmd.exe /c e manda o prompt por stdin (-), o que evita quebrar com aspas e acento.
• Lote em paralelo pode, desde que pelo script. Uma versão antiga cortava pelo "PNG mais novo da pasta", e num lote de 8 duas execuções simultâneas roubaram arquivo uma da outra: dois nomes diferentes com bytes idênticos e um objeto faltando. O corte por thread_id resolveu. Ao matar um lote, mate também os processos codex órfãos, que continuam gerando depois do shell morrer.
• Uma chamada pode devolver mais de uma imagem. O Codex às vezes refaz por conta própria. O script salva as duas, a segunda com sufixo -2. Olhe as duas antes de escolher.
• Se o script disser "nenhuma imagem nova", a causa quase sempre é o Codex ter decidido responder em texto em vez de chamar a ferramenta. Rode com --seco, leia o prompt e deixe o pedido de imagem mais direto. A segunda causa é login vencido: codex login.