Codex: генерация изображений через свой провайдер и imagegen

Чтобы включить генерацию изображений в Codex через свой провайдер (релей), хватит двух строк в config.toml: записи http_headers с именем x-openai-actor-authorization и любым непустым значением и requires_openai_auth = false — это значение по умолчанию. После этого Codex 0.165.0 отправляет запросы изображений на /images/generations релея с моделью gpt-image-2 и сохраняет PNG в ~/.codex/generated_images/. 29 октября 2026 года это дало PNG 1024×1024 за 29.0 секунды; с той же конфигурацией без заголовка инструмент изображений не появлялся.

Проверяли на Codex CLI 0.165.0 под macOS, а в роли своего провайдера использовали OmniaKey — наш собственный шлюз API.

Почему imagegen исчезает на своём провайдере

Codex 0.165.0 решает, получит ли модель инструмент изображений, в одной функции — image_generation_available, — глядя на блок провайдера и сохранённый вход.

• requires_openai_auth = false без заголовка актора: инструмента изображений нет. В нашем запуске с такой конфигурацией Codex ответил: "I don’t have a built-in image generation tool available in this session." (В этой сессии нет встроенного инструмента генерации изображений.)
• requires_openai_auth = false плюс заголовок x-openai-actor-authorization: инструмент появляется. Все три наших запуска с ним (новое изображение, правка и прозрачный стикер) его вызвали.
• requires_openai_auth = true со входом по API-ключу: инструмента изображений нет. По коду Codex 0.165.0 проверка требует входа в ChatGPT, а API-ключ не считается.

За этой проверкой стоят два меньших условия, оба в коде Codex 0.165.0: сохранённый вход в бесплатный тариф ChatGPT скрывает инструмент даже на своём провайдере, а чат-модель должна принимать изображения — Codex предполагает это для названий моделей, которых нет в его собственном списке.

Когда инструмента нет, Codex либо говорит, что встроенного инструмента изображений нет, как в нашем запуске без заголовка, либо навык imagegen предлагает запасной путь через CLI, для которого нужен OPENAI_API_KEY.

config.toml, который его включает

Откройте ~/.codex/config.toml. В блоке провайдера для вашего релея добавьте строку http_headers и убедитесь, что requires_openai_auth стоит в false — это значение по умолчанию.

model = "gpt-6.1-sol"            # чат-модель, которую отдаёт ваш релей
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          # в Codex 0.165.0 уже включено по умолчанию

• requires_openai_auth = false оставляет Codex на ключе из вашего окружения — переменной, указанной в env_key. Страница аутентификации OpenAI (проверена 29 октября 2026 года) говорит: "When requires_openai_auth = true, Codex ignores env_key." (При requires_openai_auth = true Codex игнорирует env_key.)
• В http_headers лежит заголовок актора. Справочник по конфигурации OpenAI называет его "Static HTTP headers added to provider requests" (фиксированные HTTP-заголовки, которые добавляются к запросам к провайдеру), а Codex проверяет только, что значение не пустое (проверка в исходниках Codex), так что "local-relay" — заполнитель, а не пароль.
• [features] image_generation = true в 0.165.0 можно не писать: функция стабильна и включена по умолчанию (codex features list выводит image_generation stable true). В наших запусках этой строки не было.
• wire_api = "responses" — единственное значение, которое поддерживает справочник по конфигурации OpenAI.

Задайте ключ и запустите Codex:

export RELAY_API_KEY="your-relay-key"
codex

Если Codex уже работал, закройте его и откройте новую сессию, чтобы он прочитал конфигурацию.

Сгенерируйте изображение и найдите файл

Наши запуски 29 октября 2026 года шли через своего провайдера. Запуск 2, проверка без заголовка, изображения не дал. Остальные три сохранили по одному PNG 1024×1024. Время относится к вызову изображения, а не ко всему ходу.

Запуск 1 — один промпт:

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.

Codex сам открыл навык imagegen, хотя в промпте не было $imagegen, и только потом вызвал инструмент. Вызов занял 29.0 секунды, и ход закончился одним PNG 1024×1024.

Файл попадает в ~/.codex/generated_images/<session id>/<call id>.png; ~/.codex — значение CODEX_HOME по умолчанию. Codex напечатал путь, потому что промпт об этом просил. Если изображение нужно в проекте, укажите место в промпте: тогда навык велит Codex переместить или скопировать файл туда.

Изменить существующее изображение

PNG из запуска 1 переехал в рабочую папку как inkwell.png, и мы попросили:

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.

Codex передал файл в referenced_image_paths, поэтому запрос ушёл на /images/edits. Вызов занял 37.6 секунды, а исходный inkwell.png остался прежним. Страница о генерации изображений OpenAI (проверена 29 октября 2026 года) говорит: "When editing an existing image, say exactly what should change and what must stay the same." (При правке существующего изображения точно скажите, что должно измениться, а что остаться прежним.) Остальное разобрано в руководстве по промптам GPT-Image 2.

Новое изображение

После одной правки

Прозрачный фон

В запуске 4 мы попросили стикер:

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.

Codex выставил transparent_background: true, вызов занял 19.8 секунды, и 85.0% пикселей сохранённого PNG полностью прозрачны. Справочник Images API OpenAI относит прозрачный фон для gpt-image-2 к "in preview" (в предпросмотре): в нашем запуске это сработало, но функция по-прежнему в предпросмотре.

Что должен вернуть ваш релей (gpt-image-2, b64_json)

Codex отправляет POST <base_url>/images/generations для нового изображения и POST <base_url>/images/edits для правки, оба в JSON с моделью gpt-image-2 — id GPT-Image 2, которую ваш релей должен обслуживать. Качество и размер идут как "auto", background — "opaque" или "transparent", а response_format и n в запросе отсутствуют. Всё уходит на тот же базовый URL и с тем же ключом, что и запросы чата. Правка несёт исходное изображение внутри JSON как data URL, а не загружает файл.

Codex читает ответ JSON с created и списком data, в первом элементе которого лежит b64_json; остальные поля игнорируются, как показывает images.rs. Ошибка разбора начинается с "failed to decode image generation response:".

Релей можно проверить без Codex. Сохраните это как relay-check.sh:

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]))'

Направьте базовый URL на свой релей и экспортируйте ключ как RELAY_API_KEY. 29 октября 2026 года проверка против нашего шлюза вернула HTTP 200 через 25.0 секунды и напечатала:

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

Если b64_json в этом списке нет, Codex падает на таком же ответе. Если релей возвращает ошибку, проверка печатает её.

Некоторые релеи ломаются здесь, потому что хранят изображение файлом. Тот же справочник Images API (проверен 29 октября 2026 года) называет response_format "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images" (устаревший параметр формата ответа для снятых с поддержки моделей изображений; модели GPT-image его не поддерживают и всегда возвращают изображения в base64), а b64_json — "Returned by default for GPT image models" (возвращается по умолчанию для моделей GPT-image). Релей, который передаёт ответ OpenAI без изменений, работает; тот, что возвращает только ссылку, ломает Codex.

Шлюз OmniaKey страдал от этого до исправления 29 октября 2026 года. В заметке об исправлении сказано, что Codex падал с "missing field b64_json", а теперь шлюз сохраняет b64_json, если вызывающая сторона не просит URL.

Если ваш релей не проходит проверку, OmniaKey отдаёт gpt-image-2 и чат-модели вроде gpt-6.1-sol по одному ключу, а в ответах на изображения есть b64_json, как показывает проверка. Поставьте base_url = "https://api.omniakey.com/v1" в этот блок провайдера и ключ OmniaKey в переменную, указанную в env_key; остальное описано в руководстве по Codex CLI, а текущие цены — на странице цен.

Ошибки и решения

Codex говорит, что инструмента изображений нет

Одно из условий первого раздела не выполнено. Добавьте строку http_headers, оставьте requires_openai_auth = false со своим env_key и начните новую сессию. Не помогло? Запустите codex login status; при бесплатном тарифе ChatGPT codex logout удаляет сохранённый вход, и ключа из env_key достаточно.

Codex просит OPENAI_API_KEY

Встроенный инструмент недоступен, поэтому навык imagegen предлагает запасной путь через CLI — scripts/image_gen.py, для которого нужен OPENAI_API_KEY. Лучше почините встроенный инструмент конфигурацией выше; во встроенном режиме ключ берётся из env_key.

failed to decode image generation response: missing field b64_json

Релей ответил без b64_json, чаще всего ссылкой на сохранённый файл. Запустите проверку из раздела о релее и отправьте результат тому, кто его обслуживает; Codex нужна строка base64 в первом элементе data.

Запрос изображения падает с model_not_found

У вашего ключа нет gpt-image-2 на этом релее, а Codex всегда отправляет этот id, и настройки, чтобы его изменить, нет. Наш шлюз ответил на модель изображений, которую не обслуживает, кодом HTTP 503 и ошибкой model_not_found. Возьмите ключ и релей, где gpt-image-2 есть в списке.

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

Запрос чата оборвался, и Codex повторил его; счётчик показывает попытку из пяти. Это появилось один раз в запуске 1 ("Concurrency limit exceeded for account, please retry later") и один раз в запуске 3 (ошибка передачи), и оба запуска завершились после повтора. Если повторяется, проверьте лимиты релея; проблемы чата разобраны в наборе совместимости Codex.

Частые вопросы

Нужен ли OPENAI_API_KEY для imagegen?

Нет. Во встроенном режиме ключ берётся из переменной, указанной в env_key; OPENAI_API_KEY читает только запасной путь навыка через CLI.

Можно выбрать другую модель изображений, размер или качество?

В Codex 0.165.0 — нет. Инструмент отправляет gpt-image-2 с качеством и размером "auto", в config.toml для этого нет ключа, и все изображения из наших запусков приходили 1024×1024. Для другого размера или модели вызывайте эндпоинт изображений своего релея напрямую.

Нужно ли самому писать $imagegen?

Нет. В наших запусках Codex открывал навык imagegen сам. Документация OpenAI говорит, что $imagegen в промпте вызывает навык явно, и это помогает, когда Codex не выбирает его сам.

Работает ли это в приложении Codex для десктопа?

Десктопное приложение мы не тестировали, только CLI. Репозиторий с исправлением от сообщества говорит, что запущенный Codex Desktop не подхватывает новые переменные окружения: его скрипт для macOS ставит LaunchAgent, после чего нужно полностью закрыть Codex и открыть новую задачу.

Проверенные источники

• Документация OpenAI Codex: аутентификация для альтернативных провайдеров моделей
• Документация OpenAI Codex: справочник по конфигурации
• Документация OpenAI Codex: генерация изображений
• Справочник API OpenAI: создание изображения
• Исходники Codex 0.165.0: когда предлагается инструмент изображений
• Исходники Codex 0.165.0: проверка заголовка актора
• Исходники Codex 0.165.0: как читается ответ с изображением
• xianyu110/codex-imagegen-relay-fix на GitHub