OpenAI API из России в 2026: как перенести интеграцию на шлюз без сюрпризов

OpenAI API из России в 2026: перенос интеграции на шлюз без сюрпризов
OpenAI API из России в 2026: перенос интеграции на шлюз без сюрпризов

Перенести интеграцию OpenAI API из России на шлюз в 2026 году технически просто: меняете ключ и base_url, и код снова отвечает. Сюрпризы начинаются потом, когда выясняется, что модель называется в каталоге иначе, JSON пришёл без нужного поля, поток оборвался на середине, а расход виден совсем в другом месте. Поэтому до переключения трафика стоит сверить шесть вещей: адрес и ключ, ID модели, схему ответа и инструменты, поток, обработку ошибок и учёт расхода.

Ниже разберу их на одной задаче и покажу, как это выглядит на примере российского шлюза Provod, чтобы вы переносили интеграцию с понятным критерием готовности.

Что такое OpenAI API и почему из России он упирается в список стран

Совсем коротко: OpenAI API это способ отдать модели запрос из своего кода и получить ответ в машинном виде, без окна чата. Ваш бэкенд отправляет JSON с сообщениями, OpenAI возвращает JSON с текстом, причиной остановки и счётчиком токенов, а деньги списываются с баланса аккаунта на platform.openai.com по API-ключу.

У прямого доступа есть условие, о котором при миграции обычно вспоминают последним. OpenAI публикует список стран и территорий API, и на 12.11.2026 России в нём нет, Беларуси тоже. На той же странице OpenAI предупреждает, что доступ к сервисам вне перечисленных стран может закончиться блокировкой или приостановкой аккаунта.

Тут полезно развести три вещи, которые в разговорах сливаются в одну:

  • ChatGPT в браузере или в приложении живёт по своим правилам подписки и доступа;
  • прямой OpenAI API работает через аккаунт разработчика, ключ OpenAI и оплату в долларах;
  • ключ шлюза выдаёт сама платформа-посредник, она же принимает оплату и сама ходит к модели.

У разных поставщиков списки стран тоже разные, и это стоит держать в голове, если в проекте несколько моделей. Например, у Anthropic отдельная страница регионов Claude, и проверять её нужно отдельно от списка OpenAI.

Отсюда и типичный сценарий команды из России: интеграция написана под официальный SDK OpenAI, а маршрут к модели нужно менять на шлюз. Вариантов много, от международного OpenRouter до российских агрегаторов, и выбирают между ними обычно по каталогу, цене за токен и способу оплаты. Я дальше разбираю Provod, потому что у него открытая документация по миграции с SDK OpenAI, и на ней удобно показать, что именно меняется в контракте.

Что меняется, когда вы меняете шлюз

Миграцию удобно представлять как подписание нового контракта с тем, кто отвечает на ваши запросы. Формат запроса может совпадать почти полностью, а условия вокруг него у шлюза свои. Пройдусь по шести пунктам в том порядке, в каком они обычно ломаются.

Начну с адреса и ключа. В руководстве по миграции Provod клиент OpenAI SDK создаётся с базовым адресом https://api.provod.ai/v1 и ключом Provod вместо ключа OpenAI. Ключ здесь принадлежит рабочему пространству Provod и с вашим OpenAI-ключом никак не связан: он показывается целиком один раз, а хранить его советуют на сервере, отдельным для каждого проекта. Там же есть две мелкие ловушки, на которых спотыкаются чаще всего: удвоенный /v1 в пути и SDK, который сам уходит на /v1/responses, хотя вы ждали Chat Completions.

Дальше идёт ID модели. В своём коде вы наверняка держите константу вроде gpt-5.4-mini. Документация по выбору модели просит брать поле id из GET /v1/models и копировать его точно, не сокращая и не собирая из названия на витрине. В примере Chat Completions этот ID записан с префиксом производителя, openai/gpt-5.4, поэтому старую константу из кода лучше не переносить вслепую. В том же ответе каталога есть поле available: если там false, рядом лежит причина, и для части моделей личного пространства это FIRST_TOP_UP_REQUIRED, то есть модель откроется после первого реального пополнения.

Со схемой ответа и инструментами история тоньше. Для строгого JSON вам нужен response_format с json_schema, а для вызова функций агентом нужен tools. В Provod поддержку таких параметров показывает поле supported_parameters у конкретной модели, и документация отдельно предупреждает, что присутствие модели в каталоге ещё не гарантирует структурированный ответ. Проверять это нужно для той модели, которую вы реально поставите в продакшен.

Поток ломается тише всего. По описанию Chat Completions потоковый ответ приходит событиями SSE, у каждого фрагмента finish_reason равен null до самого конца, а нормальное завершение отмечено строкой data: [DONE]. Документация честно перечисляет три способа сломаться: ошибка JSON до начала потока, событие ошибки внутри потока и обрыв соединения до [DONE]. Код, который считает ответ готовым просто потому, что соединение закрылось, на новом маршруте рано или поздно покажет пользователю половину текста.

С ошибками своя кухня. Обычная ошибка Chat Completions в Provod приходит объектом error с полями code, message, param и type, но для части ошибок модели и баланса добавляются поля верхнего уровня, например resetAt или topUpUrl. По странице ошибок 401 означает проблему с ключом, 402 нехватку доступного баланса, 429 лимит, включая исчерпанный лимит расхода ключа API_KEY_SPEND_LIMIT_EXCEEDED. Обработчик, заточенный под коды OpenAI и смотрящий только на HTTP-статус, на новом маршруте будет путать «кончились деньги» с «превышен лимит».

Остаётся учёт расхода. У прямого API деньги считаются в долларах в кабинете OpenAI, а в ответе вы видите только токены. Provod, по документации о стоимости использования, для Chat Completions и Responses возвращает фактическое списание прямо в ответе, в полях usage.cost и usage.currency, а в кабинете в разделе «Использование» можно отфильтровать запросы по пространству, периоду и ключу и увидеть модель, токены, кэш и итоговую сумму. Токены рассуждений там всегда входят в стоимость, даже если отдельного счётчика в отчёте нет.

Миграция OpenAI API на шлюз: шесть пунктов нового контракта
Миграция OpenAI API на шлюз: шесть пунктов нового контракта

Какие проверки нужны вашей задаче, а какие можно просто отметить

Проверять все шесть пунктов с одинаковой глубиной незачем, глубину каждой проверки задаёт ваша задача.

Вот вам пример: сервис раскладывает входящие обращения по категориям и складывает результат в базу. Для него главное это схема ответа и ошибки, потому что сломанный JSON молча испортит данные. Поток такому сервису не нужен вовсе, его достаточно отметить как «не используем».

У чат-бота поддержки картина обратная. Пользователь видит текст по мере генерации, значит, на первое место выходит обработка обрыва потока и правило повторов. Provod прямо просит не повторять вслепую уже начавшийся ответ и после обрыва искать стоимость генерации по сохранённому заголовку x-generation-id, без повторного запуска.

Агенту с функциями важнее всего инструменты. Если вы работаете через Responses API, имейте в виду, что переносимый вариант в Provod поддерживает function tools, структурированный вывод и Conversations, но намеренно отклоняет hosted-инструменты: web_search, file_search, code_interpreter, computer use, hosted MCP и фоновые задачи. Функции при этом выполняются в вашей среде, шлюз ваш код не запускает. Логику, которая держится на встроенном веб-поиске OpenAI, одной заменой адреса не перенести.

И есть пункт, который стоит проверить первым, до всех остальных: какие методы API вообще использует ваш код. Руководство по миграции Provod прямо пишет, что замена baseURL не добавляет все адреса OpenAI. Опубликованы Chat Completions, Responses, Conversations, список моделей и методы для изображений, а эмбеддинги, транскрибация и перевод аудио на 12.11.2026 не опубликованы. Когда ваш поиск по базе знаний строится на эмбеддингах OpenAI, для этой части понадобится отдельное решение.

Какие проверки OpenAI API нужны при смене шлюза для вашей задачи
Какие проверки OpenAI API нужны при смене шлюза для вашей задачи

Один вход, один ожидаемый JSON: как сравнить два маршрута

Чтобы сравнение было честным, возьмите одну задачу с заранее известным правильным ответом. Я взял классификацию обращения: на входе обезличенный текст «Мне дважды списали деньги за подписку, верните одно списание», на выходе ожидается ровно {"category":"billing"}.

Сразу оговорюсь, чтобы не было путаницы. Сравнение ниже документационное: оно собрано по опубликованным описаниям OpenAI и Provod, живой прямой вызов OpenAI из России я не делал и делать не советую, а запрос к Provod для этой статьи не запускался, поэтому вывод модели здесь не показан.

Прямой маршрут OpenAI API:

  • запрос: адрес https://api.openai.com/v1, ключ из кабинета OpenAI, ID модели из документации OpenAI;
  • результат по схеме: response_format с json_schema и strict для моделей, где OpenAI это поддерживает;
  • ошибка при неверной конфигурации: 401 с кодом неверного ключа, для аккаунта вне списка стран добавляется риск блокировки;
  • учёт: токены в поле usage, деньги в долларах в кабинете OpenAI.

Маршрут через Provod:

  • запрос: адрес https://api.provod.ai/v1, ключ рабочего пространства, точный id из GET /v1/models;
  • результат по схеме: тот же response_format, если json_schema есть в supported_parameters выбранной модели;
  • ошибка при неверной конфигурации: 401 с объектом error, а при пустом балансе 402 или FIRST_TOP_UP_REQUIRED со ссылкой на пополнение;
  • учёт: токены и фактическое списание в рублях в usage.cost и usage.currency, детализация в разделе «Использование».

Контрольный вызов для второго маршрута выглядит так. Ключ и ID модели лежат в переменных окружения, в коде секретов нет.

import os, json from openai import OpenAI client = OpenAI( api_key=os.environ["PROVOD_API_KEY"], base_url="https://api.provod.ai/v1", ) schema = { "name": "ticket_category", "strict": True, "schema": { "type": "object", "properties": { "category": {"type": "string", "enum": ["billing", "tech", "other"]} }, "required": ["category"], "additionalProperties": False, }, } resp = client.chat.completions.create( model=os.environ["MODEL_ID"], # точный id из GET /v1/models messages=[ {"role": "system", "content": "Определи категорию обращения."}, {"role": "user", "content": "Мне дважды списали деньги за подписку, верните одно списание"}, ], response_format={"type": "json_schema", "json_schema": schema}, max_tokens=50, ) answer = json.loads(resp.choices[0].message.content) assert answer == {"category": "billing"}, answer print(resp.choices[0].finish_reason, resp.model, resp.usage)

Основатель Provod Александр Нестеров на локальном стенде проверял, какое тело запроса собирает SDK и как обрабатываются разные варианты потока. Это наблюдение с локального стенда, замером Provod его считать нельзя, зато оно подсказывает хорошую привычку: сравнивайте содержание и форму ответа, а код 200 считайте только пропуском к этой проверке.

Вторая половина теста не менее важна. Отправьте тот же запрос с намеренно испорченным ключом и посмотрите, что поймает ваш обработчик ошибок: правильный статус, error.code и понятную запись в логе. Лучше узнать на тестовом стенде, что на испорченный ключ приложение реагирует так же, как на таймаут, чем в два часа ночи, когда упал продакшен.

Тест OpenAI API через шлюз: один вход и ожидаемый JSON
Тест OpenAI API через шлюз: один вход и ожидаемый JSON

Порядок перехода и критерий готовности

Сама миграция укладывается в короткую последовательность, и главное в ней не спешить с переключением трафика.

1. Выпустите отдельный тестовый ключ на странице API Provod и поставьте ему лимит расхода в кабинете, чтобы тест не мог потратить больше задуманного.

2. Пополните баланс того пространства, где выпущен ключ: по странице баланса физлицу доступны карта и СБП, а ООО и ИП оплачивают банковским счётом.

3. Получите GET /v1/models, найдите нужную модель с available: true и проверьте её supported_parameters под вашу задачу.

4. Отправьте один контрольный вызов из примера выше и один вызов с испорченным ключом.

5. Сверьте расход в ответе и в разделе «Использование», а свежую ставку модели в каталоге.

6. Только после этого переключайте рабочий трафик, сохранив старую конфигурацию, чтобы откатиться одной правкой.

Пара слов о деньгах на этом шаге. Перед каждым запросом Provod резервирует оценку стоимости на балансе, после ответа списывает подтверждённую сумму и возвращает остаток резерва. Резерв при этом не жёсткий потолок: подтверждённый расход может его превысить, а доставленная часть оборванного потока может оплачиваться. Поэтому на тестовом ключе лимит расхода полезнее, чем кажется.

Критерий готовности у меня получился такой: контрольный запрос вернул ровно ожидаемый JSON, finish_reason равен stop, в model видна та модель, которую вы выбирали, в usage есть токены и списание, а испорченный ключ дал 401 с понятным кодом в вашем логе. При любом несовпадении переключаться рано.

Готовность интеграции OpenAI API к переходу на шлюз: контрольный вызов
Готовность интеграции OpenAI API к переходу на шлюз: контрольный вызов

Коротко о переносе OpenAI API на шлюз

России нет в официальном списке стран OpenAI API на 12.11.2026, и OpenAI предупреждает о блокировке аккаунтов, которые обращаются к сервисам вне этого списка.

ChatGPT в браузере, прямой OpenAI API и ключ шлюза живут по разным условиям доступа и оплаты, поэтому решение по одному из них не переносится на другие автоматически.

При миграции на шлюз меняются адрес и ключ, но сверять нужно ещё ID модели, поддержку схемы и инструментов, поток, формат ошибок и учёт расхода.

Замена base_url не добавляет методы, которых шлюз не публикует, поэтому эмбеддинги, аудио и hosted-инструменты Responses стоит проверить первыми.

API ключ OpenAI и ключ рабочего пространства Provod отличаются владельцем, валютой оплаты и местом, где видна доступность модели и фактическое списание.

Интеграция OpenAI API готова к переходу, когда контрольный запрос вернул ожидаемый JSON, а ошибка конфигурации корректно поймана и записана в лог.

Когда вы как раз переносите рабочую интеграцию, начните с малого: выберите модель OpenAI в каталоге Provod, выпустите отдельный тестовый ключ на странице API и прогоните на нём тот самый запрос с ожидаемым {"category":"billing"}, прежде чем трогать продакшен.

Подробнее:

А на каком пункте споткнулись при переезде вы: ID модели, поток или ошибки? Расскажите в комментариях.