Codex: gerar imagem com imagegen e um provedor personalizado

Para gerar imagem com Codex através de um provedor personalizado (relay), bastam duas linhas no config.toml: uma entrada http_headers chamada x-openai-actor-authorization com qualquer valor não vazio, e requires_openai_auth = false, que é o padrão. Com isso, o Codex 0.165.0 envia os pedidos de imagem para /images/generations do relay com o modelo gpt-image-2 e salva o PNG em ~/.codex/generated_images/. Em 29 de outubro de 2026, isso deu um PNG de 1024×1024 em 29.0 segundos; com a mesma configuração sem o cabeçalho, nenhuma ferramenta de imagem aparecia.

Fizemos esses testes com o Codex CLI 0.165.0 no macOS, usando a OmniaKey, nosso próprio gateway de API, como provedor personalizado.

Por que o imagegen some com um provedor personalizado

O Codex 0.165.0 decide se o modelo recebe uma ferramenta de imagem em uma única função, image_generation_available, a partir do bloco do provedor e do login guardado.

requires_openai_auth = false sem o cabeçalho de ator: nenhuma ferramenta de imagem. Na nossa execução com essa configuração, o Codex respondeu: "I don’t have a built-in image generation tool available in this session." (Não tenho uma ferramenta de geração de imagens integrada disponível nesta sessão.)
requires_openai_auth = false com o cabeçalho x-openai-actor-authorization: a ferramenta aparece. Nossas três execuções com ele (uma imagem nova, uma edição e um adesivo transparente) chamaram a ferramenta.
requires_openai_auth = true com login por chave de API: nenhuma ferramenta de imagem. No código do Codex 0.165.0, a checagem exige um login do ChatGPT, e uma chave de API não conta.

Atrás desse filtro há duas condições menores, ambas no código do Codex 0.165.0: um login em plano gratuito do ChatGPT esconde a ferramenta mesmo com provedor personalizado, e o modelo de chat precisa aceitar imagens, o que o Codex presume para nomes de modelo que a própria lista dele não conhece.

Quando a ferramenta falta, o Codex diz que não tem ferramenta de imagem integrada, como na nossa execução sem o cabeçalho, ou a skill imagegen oferece o atalho por CLI, que precisa de OPENAI_API_KEY.

O config.toml que ativa o imagegen

Abra ~/.codex/config.toml. No bloco do provedor do seu relay, adicione a linha http_headers e confirme que requires_openai_auth está em false, o padrão.

toml

model = "gpt-6.1-sol"            # um modelo de chat que o seu relay serve
model_provider = "relay"

[model_providers.relay]
name = "My relay"
base_url = "https://api.omniakey.com/v1"
env_key = "RELAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
http_headers = { "x-openai-actor-authorization" = "local-relay" }

[features]
image_generation = true          # já vem ligado por padrão no Codex 0.165.0

model e model_provider são chaves de nível superior, então ficam acima da primeira linha [section]: o TOML lê todas as linhas depois de um cabeçalho [section] como parte daquela seção.

requires_openai_auth = false mantém o Codex usando a chave do seu ambiente, a variável indicada em env_key. A página de autenticação da OpenAI (conferida em 29 de outubro de 2026) diz: "When requires_openai_auth = true, Codex ignores env_key." (Com requires_openai_auth = true, o Codex ignora env_key.)
http_headers guarda o cabeçalho de ator. A referência de configuração da OpenAI o chama de "Static HTTP headers added to provider requests" (cabeçalhos HTTP fixos adicionados aos pedidos ao provedor), e o Codex só confere se o valor não está vazio (a checagem no código do Codex), então "local-relay" é um marcador de posição, não uma senha.
[features] image_generation = true é opcional no 0.165.0, onde o recurso é estável e vem ligado por padrão (codex features list imprime image_generation stable true). Nas nossas execuções não escrevemos essa linha.
wire_api = "responses" é o único valor aceito pela referência de configuração da OpenAI.

Defina a chave e inicie o Codex:

bash

export RELAY_API_KEY="your-relay-key"
codex

Se o Codex já estava rodando, feche e abra uma sessão nova para ele ler a configuração.

Gere uma imagem e encontre o arquivo

Nossas execuções de 29 de outubro de 2026 passaram por um provedor personalizado. A execução 2, a verificação sem o cabeçalho, não gerou imagem. As outras três salvaram um PNG de 1024×1024 cada uma. Os tempos são da chamada de imagem, não do turno inteiro.

Execução	O que pedimos	Chamada de imagem
1	Um ícone de app novo	29.0 s
3	Editar a imagem da execução 1	37.6 s
4	Um adesivo transparente	19.8 s

A execução 1 foi um prompt só:

Create an app icon for a note-taking app called Inkwell: a fountain pen nib over a deep blue gradient, flat vector style, no text. Generate it with your image tool, then tell me where the file was saved.

O Codex abriu a skill imagegen sozinho, sem $imagegen no prompt, e depois chamou a ferramenta. A chamada levou 29.0 segundos e o turno terminou com um PNG de 1024×1024.

O arquivo fica em ~/.codex/generated_images/<session id>/<call id>.png; ~/.codex é o CODEX_HOME padrão. O Codex imprimiu o caminho porque o prompt pedia. Se a imagem for para o seu projeto, indique o destino no prompt: a skill manda o Codex mover ou copiar o arquivo para lá.

Editar uma imagem existente

O PNG da execução 1 foi para a pasta de trabalho como inkwell.png, e pedimos:

Edit the image ./inkwell.png: change the background to a warm orange gradient and keep the pen nib as it is. Use your built-in image tool, then tell me where the edited file was saved.

O Codex passou o arquivo em referenced_image_paths, então o pedido foi para /images/edits. A chamada levou 37.6 segundos e o inkwell.png original ficou como estava. A página de geração de imagens da OpenAI (conferida em 29 de outubro de 2026) diz: "When editing an existing image, say exactly what should change and what must stay the same." (Ao editar uma imagem existente, diga exatamente o que deve mudar e o que deve continuar igual.) O resto está no guia de prompts do GPT-Image 2.

Imagem nova

Depois de uma edição

As duas imagens saíram da ferramenta de imagem integrada do Codex CLI 0.165.0, via provedor personalizado, em 29 de outubro de 2026. A edição pedia só um fundo novo; a ponta manteve forma, tamanho e posição.

Fundo transparente

A execução 4 pediu um adesivo:

Create a PNG sticker of a single fountain pen nib on a fully transparent background (no backdrop at all), flat vector style, no text. Generate it with your built-in image tool, then tell me where the file was saved.

O Codex definiu transparent_background: true, a chamada levou 19.8 segundos e 85.0% dos pixels do PNG salvo são totalmente transparentes. A referência da Images API da OpenAI lista fundos transparentes para o gpt-image-2 como "in preview" (em prévia): funcionou na nossa execução, mas o recurso continua em prévia.

Execução 4 de 29 de outubro de 2026: um PNG com fundo transparente, mostrado sobre um tabuleiro xadrez para a área transparente aparecer. 85.0% dos pixels são totalmente transparentes.

O que o seu relay precisa devolver (gpt-image-2, b64_json)

O Codex envia POST <base_url>/images/generations para uma imagem nova e POST <base_url>/images/edits para uma edição, os dois em JSON com o modelo gpt-image-2, o id do GPT-Image 2, que o seu relay precisa servir. Qualidade e tamanho vão como "auto", background vai como "opaque" ou "transparent", e o pedido deixa de fora response_format e n. Tudo vai para a mesma URL base, com a mesma chave, dos seus pedidos de chat. Uma edição leva a imagem de origem dentro do JSON como data URL, em vez de enviar um arquivo.

O Codex lê uma resposta JSON com created e uma lista data cujo primeiro item traz b64_json; os outros campos são ignorados, como mostra o images.rs. Uma falha de análise começa com "failed to decode image generation response:".

Dá para conferir um relay sem o Codex. Salve isto como relay-check.sh:

bash

curl -s https://api.omniakey.com/v1/images/generations \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "a red apple on a white table", "background": "opaque", "quality": "auto", "size": "auto"}' \
  | python3 -c 'import json,sys; r=json.load(sys.stdin); print(r.get("error") or sorted(r["data"][0]))'

Aponte a URL base para o seu relay e exporte a chave como RELAY_API_KEY. Em 29 de outubro de 2026, a checagem contra o nosso gateway voltou HTTP 200 em 25.0 segundos e imprimiu:

text

['asset_id', 'b64_json', 'expires_at', 'revised_prompt', 'url']

Se b64_json faltar nessa lista, o Codex falha na mesma resposta. Se o relay devolver um erro, a checagem imprime esse erro.

Alguns relays quebram aqui porque guardam a imagem como arquivo. A mesma referência da Images API (conferida em 29 de outubro de 2026) chama response_format de "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images" (parâmetro legado de formato de resposta para modelos de imagem aposentados; não suportado nos modelos GPT de imagem, que sempre devolvem imagens em base64), e b64_json é "Returned by default for GPT image models" (devolvido por padrão nos modelos GPT de imagem). Um relay que repassa a resposta da OpenAI sem mudar nada funciona; um que devolve só um link quebra o Codex.

O gateway da OmniaKey teve esse problema até uma correção em 29 de outubro de 2026. A nota da correção diz que o Codex falhava com "missing field b64_json", e agora o gateway mantém o b64_json, a menos que quem chama peça uma URL.

Se o seu relay não passa na checagem, a OmniaKey serve gpt-image-2 e modelos de chat como gpt-6.1-sol com uma única chave, e as respostas de imagem incluem b64_json, como a checagem mostra. Coloque base_url = "https://api.omniakey.com/v1" nesse bloco do provedor e a chave da OmniaKey na variável que o env_key indica; o guia do Codex CLI cobre o resto do arquivo, e os preços atuais estão na página de preços.

Erros e soluções

O Codex diz que não tem ferramenta de imagem

Uma das condições da primeira seção não está atendida. Adicione a linha http_headers, mantenha requires_openai_auth = false com o seu env_key e abra uma sessão nova. Continua igual? Rode codex login status; com um plano gratuito do ChatGPT, codex logout apaga o login guardado e a chave do env_key basta.

O Codex pede OPENAI_API_KEY

A ferramenta integrada não está disponível, então a skill imagegen oferece o atalho por CLI, scripts/image_gen.py, que precisa de OPENAI_API_KEY. Conserte a ferramenta integrada com a configuração acima; no modo integrado a chave vem do env_key.

failed to decode image generation response: missing field b64_json

O relay respondeu sem b64_json, quase sempre com um link para um arquivo guardado. Rode a checagem da seção do relay contra ele e mande o resultado para quem opera; o Codex quer a string base64 no primeiro item de data.

O pedido de imagem falha com model_not_found

A sua chave não tem gpt-image-2 nesse relay, e o Codex sempre envia esse id, sem ajuste para mudar. Nosso gateway respondeu a um modelo de imagem que não serve com HTTP 503 e o código model_not_found. Use uma chave e um relay que listem gpt-image-2.

Reconnecting... 1/5 (stream disconnected before completion)

O pedido de chat caiu e o Codex tentou de novo; o contador mostra a tentativa entre cinco. Apareceu uma vez na execução 1 ("Concurrency limit exceeded for account, please retry later") e uma vez na execução 3 (um erro de transporte), e as duas execuções terminaram depois da nova tentativa. Se voltar sempre, confira os limites do relay; problemas de chat estão no kit de compatibilidade do Codex.

Perguntas frequentes

Preciso de OPENAI_API_KEY para o imagegen?

Não. No modo integrado a chave vem da variável indicada em env_key; só o atalho por CLI da skill lê OPENAI_API_KEY.

Posso escolher outro modelo de imagem, tamanho ou qualidade?

No Codex 0.165.0, não. A ferramenta envia gpt-image-2 com qualidade e tamanho "auto", o config.toml não tem chave para isso e todas as imagens das nossas execuções voltaram em 1024×1024. Para outro tamanho ou modelo, chame direto o endpoint de imagens do seu relay.

Preciso digitar $imagegen?

Não. Nas nossas execuções o Codex abriu a skill imagegen sozinho. A documentação da OpenAI diz que $imagegen no prompt chama a skill de forma explícita, o que ajuda quando o Codex não a escolhe.

Funciona no app de desktop do Codex?

Não testamos o app de desktop, só a CLI. O repositório da correção da comunidade diz que um Codex Desktop em execução não pega variáveis de ambiente novas: o script para macOS instala um LaunchAgent, e depois você fecha o Codex por completo e abre uma tarefa nova.

Fontes consultadas

Criar uma chave de API da OmniaKey Ver GPT-Image 2