Tarefas de imagem com Codex
Execute todo projeto ou lote de tarefas de imagem através do runner. Não chame codex exec ou codex-imagegen manualmente para
essas tarefas.
python scripts/codex_image.py "<prompt ou @prompt.txt>" out.png [--ref room.jpg] [--size 1536x1024] [--force]
Ele imprime o caminho absoluto da saída. Defina um tempo limite para a chamada Bash acima do --timeout do próprio runner (padrão 420 s).
| Saída | Significado | Ação |
|---|---|---|
| 0 | Salvo | Visualize a imagem |
| 1 | Uso, por exemplo, a saída existe | Corrija a chamada; --force substitui uma saída, nunca sua própria referência |
| 2 | Codex terminou sem imagem | Leia a saída impressa, corrija a causa e tente novamente uma vez |
| 3 | A chamada de imagem omitiu a referência, então nada foi salvo | Tente novamente uma vez com o mesmo comando |
| 124 | Nenhuma sessão ou nenhuma imagem a tempo | Verifique codex login status e a rede |
Regras
- Verifique cada saída em relação ao seu briefing. Saída 0 prova que uma imagem veio desta sessão, não que está correta.
- Encadeie edições uma mudança de cada vez: cada saída se torna o próximo
--ref. Escreva em um novo arquivo a cada etapa. - Mantenha o ambiente: diga o que não deve mudar (câmera, geometria, aberturas) e nomeie o papel de cada referência quando houver duas ou mais. Até 4 referências.
- Controle a cota. Uma execução gasta uma imagem, e execuções podem ocorrer em paralelo, mas informe a contagem antes de um lote grande e faça a primeira imagem funcionar antes do restante.
- Referências PNG com alfa: use
--keep-png-refs, pois a conversão para JPG as achata.
Por que o runner existe
Medido com codex-cli 0.164.0 em 2026-11-04, a partir dos logs de sessão de 30 execuções de imagem.
| Falha | Causa | O que o runner faz |
|---|---|---|
| Trava até o tempo limite | codex exec espera por um pipe stdin aberto: 45 s com pipe (parado por tempo limite), 4 s com ele fechado | Envia o prompt no stdin e o fecha |
| Imagem errada sob um nome | Solicitado a salvar, Codex pesquisou o diretório compartilhado ~/.codex/generated_images, pegou o mais recente e copiou a imagem de outra execução | Codex nunca salva; o runner lê apenas generated_images/<id da sessão>/ |
| Até 7 chamadas de imagem para uma saída | Codex não conseguiu encontrar como salvar, então gerou novamente | Para o Codex na primeira imagem completa |
| Referência ignorada, ambiente inventado | A ferramenta de imagem vê anexos apenas se a chamada definir num_last_images_to_include | Nomeia o parâmetro, lê o log da sessão, saída 3 se foi omitido |
| Ambiente perdido em passagens encadeadas | Cada passada de mobília alimentou um PNG e o perdeu; JPG com o parâmetro nomeado o manteve (correlação, não causa comprovada) | Converte referências PNG para JPG quando ffmpeg está no PATH |
Verificado com o CLI real no mesmo dia: três edições, duas delas em paralelo em uma referência PNG, cada uma levou cerca de 25 s e uma chamada de imagem, e cada uma manteve sua própria mudança de cor.
Se você precisar usar o codex-imagegen do plugin
codex-bridge 1.2.0 tem essas falhas. Chame-o com </dev/null, uma tarefa por vez, uma referência JPG e
"chame a ferramenta de imagem exatamente uma vez com num_last_images_to_include:1" no prompt, depois visualize o resultado.