Мост изображений

Обзор

Когда вы маршрутизируете Codex через не-OpenAI модель (Claude, Gemini, Grok и т. п.), hosted tool image_generation обычно не работает — ему нужна серверная среда исполнения OpenAI. Image Bridge обнаруживает такие вызовы и прозрачно перенаправляет их в xAI Grok Imagine, чтобы модель, с которой вы реально разговариваете, всё равно могла генерировать изображения.

Предварительные требования

• Включите мост, задав images.bridgeEnabled: true в конфигурации (по умолчанию он выключен, чтобы не создавать неожиданных расходов xAI — см. Конфигурацию ниже).

• Нужна запись провайдера xai с API-ключом. Bridge жёстко привязывает выполнение к registry-endpoint’у xAI Images (https://api.x.ai/v1); любой настроенный override baseUrl для image-вызовов игнорируется. Одного OAuth / ocx login xai для активации bridge недостаточно (OAuth-транспорт Grok CLI ориентирован на чат и не используется для /images/*).

  {
    "providers": {
      "xai": { "adapter": "openai-chat", "apiKey": "xai-…", "authMode": "key" }
    }
  }

• В качестве активного провайдера должна быть выбрана не-OpenAI модель. (Когда активный провайдер — OpenAI, нативный hosted tool используется напрямую, и bridge обходится.)

Конфигурация

Параметры Image Bridge находятся под images в ~/.opencodex/config.json. Bridging — opt-in: чтобы включить платную генерацию через xAI Grok Imagine, нужно явно задать bridgeEnabled: true:

{
  "images": {
    "bridgeEnabled": true,
    "bridgeModel": "grok-imagine-image-quality",
    "maxRounds": 3,
    "timeoutMs": 60000
  }
}

Параметр	По умолчанию	Описание
bridgeEnabled	false	Главный переключатель. Задайте true, чтобы включить bridge. По умолчанию выключен, чтобы избежать неожиданных расходов xAI.
bridgeModel	grok-imagine-image-quality	Id image-модели xAI, куда отправляются prompt’ы.
maxRounds	3	Максимум итераций цикла image-generation за один ход. Округляется вниз до целого и ограничивается диапазоном [0, 10]; нечисловые значения возвращаются к 3.
timeoutMs	60000	Дедлайн одного вызова xAI в миллисекундах. Конечные положительные значения округляются вниз и передаются в запрос xAI.
artifactsKeepCount	200	Максимум файлов, сохраняемых в artifacts/. При превышении после каждого выполненного вызова удаляются самые старые файлы. Задайте 0 или отрицательное значение, чтобы отключить pruning.

Хранение артефактов

Сгенерированные изображения записываются в ~/.opencodex/artifacts/. Чтобы в долгоживущих сессиях каталог не рос бесконечно, после каждого выполненного image-вызова он автоматически prune’ится (когда вся партия этого вызова уже записана на диск): самые старые файлы по времени модификации удаляются, если количество превышает настроенный максимум (по умолчанию 200, настраивается через images.artifactsKeepCount). Модели возвращаются только те пути, которые пережили pruning.

Как это работает

Image Bridge активируется только на Responses-ходах, где в массиве tools запроса /v1/responses есть hosted tool image_generation, а в качестве модели выбрана не-OpenAI модель. Он не перехватывает встроенный инструмент Codex image_gen, который отправляет POST напрямую в /v1/images/generations (или /images/edits) — этот путь описан отдельно в Интеграции с Codex.

1. Когда Responses-запрос перечисляет image_generation в tools, OpenCodex замечает это на этапе предобработки.
2. Hosted tool заменяется на синтетический function tool, который маршрутизируемая модель может вызвать обычным образом — вместо непрозрачного hosted tool модель видит вызываемый tool.
3. Когда модель вызывает этот tool, OpenCodex перехватывает вызов и отправляет prompt в API генерации изображений xAI.
4. Сгенерированные изображения сохраняются в ~/.opencodex/artifacts/, а локальный путь к файлу возвращается модели как результат tool.
5. Модель продолжает разговор уже зная о сгенерированном изображении и его местоположении.

С точки зрения модели ничего не изменилось: она вызвала tool и получила результат. С точки зрения пользователя генерация изображений работает с любым маршрутизируемым провайдером вместо тихого провала.

Ограничения

• Поддерживается только xAI Grok Imagine. DALL-E и другие image-провайдеры могут появиться позже.
• Приоритет у web search на адаптерах, которые поддерживают цикл web-search sidecar. Если в одном ходе одновременно запрашиваются web search и image generation, отработает web-search, а image generation будет пропущена. Адаптеры Cursor/runTurn этот sidecar сейчас не умеют, поэтому на таких dual-tool ходах image bridge всё ещё может сработать.
• Применяются расходы xAI. Генерация изображений через xAI требует активной подписки xAI или API-кредитов.
• Только streaming. Bridge работает, перехватывая SSE-поток ответа; запросы с stream: false отклоняются ошибкой 400.