MrBogomips/codex-image-gen

Geração de imagens via codex CLI

codex exec não possui uma opção "escreva a imagem neste caminho": ele salva o que gera em $CODEX_HOME/generated_images/<session id>/. scripts/codex_image.py executa uma rodada não interativa, coleta apenas as imagens dessa sessão exata e as escreve onde você pede. Se nenhuma imagem for devolvida, ele não escreve nada.

Sempre use o script. Um codex exec "desenhe um gato" feito manualmente frequentemente retorna prosa ou um desenho do ImageMagick e deixa você caçando a saída.

Nunca recorra a uma API medida. Não use o SDK da OpenAI ou OPENAI_API_KEY, mesmo quando o codex falhar ou estiver sem cota. Relate a falha e pare. Para a API medida do Google, use apenas google-image-gen, e somente quando o usuário a solicitar.

Uso

Execute a partir do diretório do skill ou forneça o caminho absoluto do script. Uma execução leva cerca de 30 a 60 segundos.

python3 scripts/codex_image.py -p "uma bicicleta vermelha solitária contra um muro de pedra molhado ao anoitecer, fotografia cinematográfica" -o bike.png

Objetivo	Comando
Proporção (uma sugestão para o modelo)	-p "..." -o out.png --aspect 9:16
Imagem(ns) de referência	-p "..." -o out.png -r ref.png [-r ref2.png]
Editar uma imagem	--edit v1.png -p "deixe o céu roxo" -o v2.png
Várias tentativas	-p "..." -o opt.png -n 3 (salva opt.png, opt-2.png, opt-3.png)
Tamanho exato em pixels	-p "..." -o cover.png --aspect 9:16 --fit 1080x1920
Prompt longo	--prompt-file prompt.md -o out.png
Ver o prompt sem gastar	adicione --print-prompt

• A extensão de saída segue o formato real: bytes PNG solicitados como bike.jpg acabam em bike.png. O script imprime cada caminho que escreveu.
• --aspect apenas molda o resultado. --fit WxH garante o tamanho depois: ele adiciona barras pretas (--fit-mode pad, padrão) ou recorta centralmente (--fit-mode crop), e sempre salva PNG. Alinhe --aspect ao alvo para que haja pouco a adicionar ou recortar. --fit precisa do Pillow, verificado antes de o codex executar.
• -n solicita N tentativas em uma rodada; o modelo pode devolver menos, e o script salva o que obteve.
• --edit anexa a imagem como alvo e diz ao modelo para alterar apenas o que o prompt pede.

Escrevendo o prompt

O script adiciona a redação que força uma chamada real de ferramenta de imagem, então --prompt é apenas sobre a figura. Uma especificação curta e rotulada funciona bem:

Assunto: uma bicicleta vermelha solitária, pintura desgastada até o metal nas bordas
Cena: encostada em um muro de pedra molhado de um porto, luzes da cidade ao fundo
Estilo: fotografia cinematográfica, profundidade de campo rasa
Iluminação: anoitecer, sol baixo e quente, reflexos na pedra molhada
Texto (literal): "SEM SOBRAS"
Evitar: pessoas, marcas d'água, bicicletas extras

• Coloque entre aspas o texto que deve aparecer e mantenha-o curto; strings longas são retornadas com erros ortográficos.
• Declare o que não deve aparecer. Para um recorte transparente, peça um fundo transparente e salve como .png.
• Para --edit, escreva a alteração ("remova o poste de luz") e nomeie o que deve permanecer ("mantenha a bicicleta, o enquadramento e a iluminação"). Altere uma coisa por passagem.
• Uma edição é uma regeneração, não um ajuste de pixel: enquadramento e detalhes se desviam, e cada passagem agrava isso. Mantenha cadeias curtas e recomponha de volta qualquer coisa que deva sobreviver intocada.

Após gerar

Verifique o resultado antes de entregá-lo, usando os meios que você tiver para olhar uma imagem: o modelo às vezes erra texto, contagens ou um detalhe solicitado. Se falhar, execute novamente com um prompt mais preciso ou refine com --edit.

Falhas

O script sai com código diferente de zero com uma mensagem clara e não escreve nada.

• CLI codex não encontrada / não logada: instale o codex e execute codex login; CODEX_BIN aponta para outro binário.
• Cota esgotada: aguarde a redefinição que o codex informa ou use outra conta. Não repita em loop.
• Nenhuma imagem produzida: o modelo respondeu em texto. A resposta é mostrada; execute novamente com um pedido de imagem mais simples.
• Tempo esgotado: aumente --timeout (padrão 900 s) apenas se a execução foi apenas lenta.
• Pillow ausente com --fit: pip install Pillow, ou remova --fit.