Codex Gateway Imagegen

O que Codex Gateway Imagegen faz?

Use esta skill para transformar um prompt em um arquivo de imagem através do gateway definido em ~/.codex/config.toml.

Ela suporta ambos:

• Geração de imagem a partir de texto (text-to-image)
• Edição de imagem com uma ou mais imagens de referência

Início Rápido

1. Confirme se o usuário deseja geração ou edição e, em seguida, confirme o caminho de saída.
2. Escolha um tamanho que corresponda ao alvo:
   • Imagem quadrada: 1024x1024
   • Retrato/captura de tela de celular: 1024x1536
   • Paisagem: 1536x1024
3. Execute scripts/generate_gateway_image.py.
4. Se a geração de imagem estiver com limite de taxa, mantenha o prompt original, imagens, tamanho e ação. Não encurte, reescreva, simplifique ou altere o prompt de forma alguma. O script auxiliar tenta novamente a mesma requisição com backoff.
5. Se a requisição falhar dentro do sandbox com erros TLS, schannel ou de tempo limite de leitura, reexecute o mesmo comando com acesso de rede do host.
6. Informe o caminho do arquivo salvo.

Fluxo de Trabalho

1. Modele o prompt

Escreva o prompt como uma especificação de produção, não como um fragmento. Inclua:

• Sujeito
• Cena
• Estilo visual
• Composição
• Iluminação
• Dicas de saída como livestream screenshot, poster, photorealistic, 9:16 vertical
• Overlays de interface ou elementos exatos na tela quando necessário

Se o usuário deseja um visual de captura de tela de aplicativo ao vivo, diga isso explicitamente e descreva os overlays.

Se o usuário deseja edição, descreva também:

• o que deve permanecer próximo à imagem de referência
• o que deve mudar
• se a edição é uma reestilização livre ou preservação de alta fidelidade

2. Escolha um tamanho válido

Padrão para 1024x1024 a menos que a composição exija claramente outra proporção.

Tamanhos conhecidos que funcionam neste fluxo:

• 1024x1024
• 1024x1536

Se o gateway retornar um erro como Invalid size ... abaixo do orçamento mínimo de pixels atual, aumente o tamanho solicitado em vez de tentar o mesmo novamente.

3. Gere com o script auxiliar

Para texto para imagem:

python "${CLAUDE_SKILL_DIR}/scripts/generate_gateway_image.py" --prompt "<prompt>" --out "<caminho-saida>" --size 1024x1024

Para edição de imagem com uma imagem de referência local:

python "${CLAUDE_SKILL_DIR}/scripts/generate_gateway_image.py" --prompt "<prompt>" --image "<imagem-referencia>" --action edit --out "<caminho-saida>" --size 1024x1536

Para edição de imagem com múltiplas referências:

python "${CLAUDE_SKILL_DIR}/scripts/generate_gateway_image.py" --prompt "<prompt>" --image "<referencia-1>" --image "<referencia-2>" --action edit --out "<caminho-saida>" --size 1024x1536

Entradas opcionais:

• --image <caminho>: imagem de referência local, repetível
• --image-url <url>: imagem de referência remota, repetível
• --mask <caminho>: máscara local para regiões de edição direcionadas
• --action auto|generate|edit: padrão é auto
• --max-retries <número>: máximo de tentativas para erros de limite de taxa de imagem, padrão é 5

O script:

• Lê base_url de ~/.codex/config.toml
• Lê OPENAI_API_KEY de ~/.codex/auth.json
• Chama /responses
• Usa model="gpt-5.5" por padrão
• Solicita a ferramenta image_generation com action=auto|generate|edit
• Envia o texto do prompt como input_text
• Envia imagens de referência como input_image
• Envia uma máscara opcional como input_image_mask
• Decodifica a imagem base64 retornada e escreve o arquivo de saída

Importante:

• O model em Responses permanece como o modelo principal, ex.: gpt-5.5
• A geração e edição de imagens são realizadas através da ferramenta image_generation
• Para edição, prefira --action edit e inclua pelo menos uma --image

4. Trate os modos de falha comuns

Se a chamada falhar dentro do sandbox com sintomas de rede ou TLS, como:

• Falha na autenticação, veja exceção interna
• schannel: AcquireCredentialsHandle falhou
• A operação de leitura expirou

trate isso primeiro como um problema de ambiente, não necessariamente de gateway. Reexecute o mesmo script fora do sandbox com acesso de rede do host.

Se a chamada chegar ao gateway e retornar um corpo de erro HTTP, inspecione o corpo antes de alterar o prompt.

Se o gateway ou stream retornar rate_limit_exceeded para geração de imagem, não altere o prompt. Tente novamente a requisição original após o atraso ou intervalo de backoff informado. Simplificação de prompt não é uma correção para limites de imagens por minuto.

Se o resultado ignorar a imagem de referência de forma muito livre:

• reforce o prompt com instruções explícitas de preservação
• mude de auto para edit
• use uma máscara quando apenas parte da imagem deve mudar

5. Salve saídas propositalmente

Se o usuário pediu uma imagem para a tarefa atual, salve-a diretamente no espaço de trabalho atual com um nome descritivo, como:

• hero_poster.png
• livestream_vertical_v2.png
• product_mockup_square.png

Não deixe o ativo final apenas em um local temporário.

Referências

• Leia references/troubleshooting.md quando a requisição falhar e você precisar da árvore de decisão rápida.