Миграция на Promptra: меняем base_url в OpenAI SDK

Чтобы перевести существующий код с OpenAI на Promptra, вы меняете ровно две вещи: base_url (на https://api.promptra.ru/v1) и api_key (на свой ключ вида prm-...). Весь остальной код — методы, параметры, обработка ответов, streaming, function calling — остаётся без единой правки. Это работает, потому что Promptra принимает запросы в формате OpenAI Chat Completions: официальный openai SDK для Python и Node не отличает Promptra от api.openai.com — для него это просто другой адрес и другой ключ. Бонусом вы получаете доступ из России без VPN и оплату в рублях на расчётный счёт юр.лица с закрывающими документами.

Ниже — рабочие примеры до/после для Python, Node/TypeScript и curl, короткие заметки по популярным обёрткам (Vercel AI SDK, LangChain), чек-лист миграции и разбор того, что именно не меняется. Синтаксис инициализации клиента сверен с актуальной документацией openai-python и openai-node — чтобы код был корректным на конец мая 2026. Тон — для разработчика, который хочет за пять минут переключить прод и не разбираться потом, почему что-то отвалилось.

Зачем вообще менять base_url

Причин ровно две, и обе практические — никакой идеологии.

Доступ из России. Прямой путь к api.openai.com, api.anthropic.com и Google из РФ упирается не в технику, а в оплату: карты с российским BIN не проходят платёжный процессор, пополнить баланс в долларах нечем, аккаунты блокируются. Это не «обход блокировки» — речь о другом. Promptra — российский сервис, который проксирует ваши запросы к провайдеру со своего юр.лица в поддерживаемой стране. Вы получаете предсказуемый доступ без VPN и без зарубежной карты: трафик не нужно туннелировать, потому что endpoint, на который вы шлёте запрос, физически доступен из России.

Оплата на юр.лицо. Это вторая, не менее важная причина для команд. Оплата идёт на юр.лицо ООО «ТРАФИК АГРЕГАТОР» (ИНН 9707022118), с полным пакетом закрывающих документов через ЭДО (Диадок/СБИС) — договор-оферта, счёт, акт, счёт-фактура, УПД. Бухгалтерия принимает расходы на AI как обычную услугу российского поставщика, без танцев с валютным контролем и платежами через третьи руки. Цена за токены — 1-в-1 с прайсом провайдера по курсу ЦБ, без наценки на сами токены; сервисная комиссия 5% берётся только при пополнении баланса.

Ключевой момент: эти две причины решаются на уровне конфигурации, а не переписыванием приложения. Вы не меняете архитектуру, не учите новый SDK, не переделываете промпты. Вы меняете адрес, куда уходит HTTP-запрос, и ключ, которым он авторизуется. Всё.

Что такое OpenAI-совместимый API

Прежде чем менять строки, стоит понять, почему это вообще работает «в одну замену». Дело в том, что OpenAI Chat Completions де-факто стал отраслевым стандартом для общения с языковыми моделями по HTTP. Формат запроса (POST /v1/chat/completions с полями model, messages, temperature, stream и т.д.) и формат ответа (choices[].message.content, дельты при стриминге) знают почти все инструменты экосистемы.

OpenAI-совместимый API — это endpoint, который принимает запросы в этом формате и возвращает ответы в нём же. Под капотом он может маршрутизировать запрос куда угодно — в саму OpenAI, в Anthropic, в Google, в DeepSeek, — но снаружи выглядит как обычный OpenAI. Именно поэтому официальный openai SDK с ним работает: SDK просто формирует стандартный HTTP-запрос и отправляет его по адресу из base_url. Кто там на другом конце — SDK не знает и ему всё равно.

Promptra — ровно такой endpoint. Адрес https://api.promptra.ru/v1 принимает запросы в формате OpenAI Chat Completions и сам транслирует их в нужного провайдера по идентификатору модели. Просите openai/gpt-5.5 — уходит в OpenAI; просите anthropic/claude-opus-4.7 — Promptra переводит запрос в формат Anthropic, получает ответ и возвращает вам обратно в формате OpenAI. Для вашего кода это всегда один и тот же интерфейс.

Практический вывод: если ваш код уже работает с OpenAI SDK, с самим OpenRouter или с любым другим OpenAI-совместимым шлюзом — миграция на Promptra это смена base_url и ключа. Разбор того же принципа на примере глобального агрегатора — в материале OpenRouter в России: как подключить.

Миграция Python SDK

Самый частый случай. Возьмём типовой кусок кода, который ходит в OpenAI напрямую.

Было — прямой запрос к OpenAI:

from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-xxxxxxxxxxxxxxxx",
    # base_url по умолчанию = https://api.openai.com/v1
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Объясни, что такое hoisting в JavaScript"}
    ],
)
print(resp.choices[0].message.content)

Стало — тот же код, меняются две строки:

from openai import OpenAI

client = OpenAI(
    api_key="prm-xxxxxxxxxxxxxxxx",            # 1. свой ключ Promptra
    base_url="https://api.promptra.ru/v1",     # 2. адрес Promptra
)

resp = client.chat.completions.create(
    model="openai/gpt-5.5",                    # (опционально) актуальная модель
    messages=[
        {"role": "user", "content": "Объясни, что такое hoisting в JavaScript"}
    ],
)
print(resp.choices[0].message.content)

Обратите внимание: client.chat.completions.create(...), структура messages, разбор resp.choices[0].message.content — всё идентично. Метод не изменился, потому что протокол тот же. Единственное, что стоит обновить кроме двух обязательных строк, — идентификатор модели (model): у Promptra он с префиксом провайдера, например openai/gpt-5.5 вместо gpt-4o. Но если вы оставите старое имя и оно есть в каталоге — запрос всё равно пройдёт; смена модели опциональна и не относится к «обязательным двум строкам».

Streaming работает без изменений — тот же флаг stream=True и та же итерация по дельтам:

stream = client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=[{"role": "user", "content": "Напиши хайку про дебаг в пятницу"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

Хорошая практика: ключ и base_url в окружении

В проде не зашивайте адрес и ключ в код. SDK от OpenAI умеет читать их из переменных окружения автоматически: api_key подхватывается из OPENAI_API_KEY, а base_url — из OPENAI_BASE_URL (это поведение по умолчанию самого openai SDK, проверено по исходникам клиента). То есть в идеале вы вообще не передаёте их в конструктор:

# .env (добавьте в .gitignore)
OPENAI_API_KEY=prm-xxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.promptra.ru/v1

from openai import OpenAI

client = OpenAI()  # api_key и base_url берутся из окружения

resp = client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=[{"role": "user", "content": "Привет!"}],
)

Плюс такого подхода: переключение между прямым OpenAI, Promptra и любым другим совместимым endpoint становится правкой одной строки в .env — без передеплоя и без правки кода. Это та же логика, что и при работе с любым multi-provider роутингом.

Миграция Node/TypeScript SDK

В Node-экосистеме всё симметрично. Параметр называется чуть иначе — baseURL (camelCase), но смысл тот же.

Было — прямой OpenAI:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-proj-xxxxxxxxxxxxxxxx",
  // baseURL по умолчанию = https://api.openai.com/v1
});

const resp = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Что такое замыкание в JS?" }],
});
console.log(resp.choices[0].message.content);

Стало — две строки:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "prm-xxxxxxxxxxxxxxxx",            // 1. свой ключ Promptra
  baseURL: "https://api.promptra.ru/v1",     // 2. адрес Promptra
});

const resp = await client.chat.completions.create({
  model: "openai/gpt-5.5",
  messages: [{ role: "user", content: "Что такое замыкание в JS?" }],
});
console.log(resp.choices[0].message.content);

Как и в Python, client.chat.completions.create(...) и разбор ответа не меняются. Streaming через async-итератор тоже работает один-в-один:

const stream = await client.chat.completions.create({
  model: "openai/gpt-5.5",
  messages: [{ role: "user", content: "Считай от одного до пяти" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Аналогично Python, держите ключ и адрес в окружении (process.env), а не в коде. SDK для Node по умолчанию читает apiKey из OPENAI_API_KEY; baseURL удобно тоже вынести в переменную и подставлять из process.env.OPENAI_BASE_URL. Тогда смена провайдера — это правка .env, а не релиз.

Миграция через curl

Если вы дёргаете API напрямую из shell-скриптов, CI или из языка, где нет официального SDK, всё ещё проще — меняется хост в URL и токен в заголовке Authorization.

Было — прямой OpenAI:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-proj-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Ответь одним словом: работает?"}]
  }'

Стало — меняем хост и токен:

curl https://api.promptra.ru/v1/chat/completions \
  -H "Authorization: Bearer prm-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "messages": [{"role": "user", "content": "Ответь одним словом: работает?"}]
  }'

Если в ответе пришёл JSON с полем choices, внутри которого message.content с текстом, — endpoint и ключ в порядке. Это самый быстрый способ проверить, что миграция в принципе живая, ещё до правки кода приложения. Коды ошибок стандартные: 401 — проблема с токеном или заголовком, 404 по модели — неверный идентификатор (проверьте префикс провайдера), 429 — кончился баланс или сработал rate limit.

Популярные обёртки: AI SDK, LangChain

Многие пишут не на голом SDK, а через фреймворк-обёртку. Хорошая новость: раз они умеют работать с OpenAI, они умеют работать и с любым OpenAI-совместимым endpoint — нужно лишь задать кастомные baseURL/base_url и ключ. Конкретные имена параметров и сигнатуры всегда смотрите в актуальной документации соответствующей библиотеки — здесь даём общий принцип, а не построчный рецепт.

Vercel AI SDK. Провайдер @ai-sdk/openai поддерживает создание кастомного инстанса через фабрику createOpenAI({ baseURL, apiKey }). Вы создаёте провайдер с адресом Promptra, а дальше используете его в generateText/streamText как обычно. Для OpenAI-совместимых шлюзов у Vercel есть и отдельный пакет-провайдер совместимости — если стандартный провайдер где-то капризничает на нестандартных полях, он часто оказывается надёжнее. Проверьте текущее имя и опции пакета в документации Vercel AI SDK.

LangChain. Класс ChatOpenAI (в Python и в JS) принимает base_url/configuration.baseURL и api_key. То есть вы инициализируете ChatOpenAI с адресом Promptra и своим ключом, а вся остальная обвязка LangChain — цепочки, агенты, ретриверы — работает без изменений, потому что под капотом это тот же OpenAI-клиент. Точные имена аргументов сверяйте с документацией LangChain, они иногда меняются между версиями.

Общее правило для любой обёртки: ищите в её настройках OpenAI-провайдера поля «base URL» / «custom endpoint» и «API key». Если они есть — Promptra подключается туда же, куда вы вписали бы свой ключ OpenAI. Если инструмент умеет в «custom OpenAI-compatible provider» — он, скорее всего, заработает с Promptra без доработок. Тот же принцип применим и к dev-инструментам: разбор настройки агентного CLI — в гайде Claude Code в России на своём API-ключе.

Что НЕ меняется при миграции

Стоит явно перечислить, чтобы снять тревогу «а вдруг что-то отвалится». При смене только base_url и api_key остаётся нетронутым:

• Методы SDK. chat.completions.create, embeddings.create, audio.transcriptions.create и прочие вызываются точно так же.
• Структура запроса. Поля model, messages, temperature, top_p, max_tokens, stop, seed — все на месте и работают как в OpenAI.
• Streaming. Флаг stream=True/stream: true и итерация по дельтам — без изменений.
• Function calling и tools. Передача tools, tool_choice и разбор tool_calls в ответе — тот же формат.
• Structured output. response_format с JSON-схемой работает там, где модель его поддерживает.
• Обработка ответа. resp.choices[0].message.content, usage с числом токенов, дельты стрима — всё в привычных местах.
• Бизнес-логика. Ваши цепочки, ретраи, парсинг, кеш — ничего этого касаться не нужно.

Единственное, что стоит (но не обязано) поменяться помимо двух строк, — это имя модели. У Promptra идентификаторы с префиксом провайдера: openai/gpt-5.5, anthropic/claude-opus-4.7, google/gemini-3.1-pro-preview, deepseek/deepseek-v4-pro. Это, кстати, и преимущество: переключение между моделями (хоть между провайдерами) — это смена одной строки model, без нового SDK и нового ключа. Можно гонять дешёвую модель на массовые запросы и флагман на сложные, оставаясь в одном клиенте.

Какие модели доступны и сколько стоят

После миграции вам доступен весь каталог Promptra через тот же клиент. Рублёвые цены — 1-в-1 из каталога (курс ЦБ 71.668 ₽/$ на 2026-05-27), без наценки на токены.

Цены 1-в-1 с официальными прайсами провайдеров: OpenAI, Anthropic, Google, DeepSeek. Пара оговорок по тарификации, которые полезно держать в голове: у DeepSeek V4 Pro текущая ставка включает промо-скидку −75% до 2026-05-31 (после неё базовый тариф вырастет примерно вчетверо — ориентировочно до $1.74/$3.48 за 1M). У GPT-5.5 при входном контексте свыше 272K токенов OpenAI переключает тарификацию на повышенную — 2× за вход и 1.5× за выход (это производная ставка от каталожных USD). Подробнее по подключению конкретных моделей — на страницах API ChatGPT/GPT и API Claude.

Биллинг в рублях: как это устроено

Главное отличие от прямого OpenAI — не в коде, а в том, как считаются и оплачиваются деньги. Разберём по пунктам, потому что для команды это часто решающий фактор.

Оплата на юр.лицо. Договор и платёж идут на ООО «ТРАФИК АГРЕГАТОР» (ИНН 9707022118). Это российский поставщик услуг — для бухгалтерии расход на AI выглядит как обычная закупка у отечественного контрагента, а не как трансграничный платёж в долларах. Никакого валютного контроля и платежей через посредников с непонятным назначением.

Полный пакет закрывающих документов. Через ЭДО (Диадок/СБИС) вы получаете договор-оферту, счёт, акт, счёт-фактуру и УПД. Этого достаточно, чтобы корректно поставить расход на затраты и не иметь вопросов при проверке. Юридическую сторону работы на компанию мы разбирали отдельно — легально ли использовать OpenAI/Claude на юрлицо в РФ.

Цена за токены 1-в-1 с провайдером. Promptra не наценивает сами токены: вы платите ровно столько, сколько стоит запрос у OpenAI/Anthropic/Google, пересчитанное в рубли по курсу ЦБ. Сервисная комиссия 5% берётся только при пополнении баланса — то есть один раз с суммы депозита, а не с каждого запроса.

Pay-as-you-go. Платите за фактическое использование: нет запросов — нет расходов. Баланс пополняется заранее, токены списываются по факту. На стороне сервиса есть дашборд с балансом и расходом — в первые дни после миграции имеет смысл туда заглядывать, чтобы откалибровать ожидания по бюджету.

С точки зрения кода всё это не меняет ничего: тот же OpenAI-совместимый API, тот же клиент, те же две строки конфигурации. Вы просто получаете предсказуемый доступ к моделям и нормальные документы для бухгалтерии. Если нужен RAG или семантический поиск, эмбеддинги подключаются через тот же endpoint — разбор в материале Embeddings API в России: поиск и RAG.

Чек-лист миграции

Сведём всё к последовательности действий. На рабочем проекте это занимает несколько минут.

1. Получить ключ и адрес. Оформить договор-оферту на юр.лицо, получить ключ вида prm-... и пополнить баланс. Адрес endpoint — https://api.promptra.ru/v1.
2. Поменять base_url. В инициализации клиента указать https://api.promptra.ru/v1 (Python — base_url, Node — baseURL, curl — хост в URL).
3. Поменять api_key. Подставить свой ключ prm-... (Python/Node — api_key/apiKey, curl — заголовок Authorization: Bearer).
4. Вынести в окружение. Положить ключ и адрес в .env (OPENAI_API_KEY, OPENAI_BASE_URL), добавить .env в .gitignore.
5. Обновить имена моделей (опционально). Сменить model на идентификаторы с префиксом провайдера — openai/gpt-5.5, anthropic/claude-opus-4.7 и т.д.
6. Проверить curl-ом. Дёрнуть https://api.promptra.ru/v1/chat/completions и убедиться, что в ответе есть choices[].message.content.
7. Прогнать тесты приложения. Запустить существующие интеграционные тесты — раз протокол тот же, они должны пройти без правок.

Если на каком-то шаге что-то не сходится — почти всегда дело в одной из трёх вещей: ключ попал не в тот заголовок, в адресе потерялся /v1, или идентификатор модели не совпал с каталогом. Все три чинятся за минуту.

FAQ

Нужно ли менять код кроме base_url?

Кроме base_url обязательно меняется только api_key — это и есть «две строки». Всё остальное (методы chat.completions, структура messages, параметры, streaming, function calling, обработка ответа, бизнес-логика) остаётся без изменений, потому что Promptra использует тот же формат OpenAI Chat Completions. Опционально стоит обновить идентификатор модели на вариант с префиксом провайдера (openai/gpt-5.5), но и это не обязательно, если нужная модель уже есть в каталоге под привычным именем.

Какие модели доступны через Promptra?

Через один OpenAI-совместимый endpoint доступны флагманы всех основных провайдеров: GPT-5.5 и GPT 5.3 Codex (OpenAI), Claude Opus 4.7 и Sonnet 4.6 (Anthropic), Gemini 3.1 Pro (Google), DeepSeek V4 Pro и другие open-weight модели. Переключение между ними — это смена строки model в запросе, без нового SDK и нового ключа. Полный список и цены в рублях — в каталоге на сайте.

Как платить из России?

Оплата идёт на юр.лицо ООО «ТРАФИК АГРЕГАТОР» (ИНН 9707022118) в рублях, с полным пакетом закрывающих документов через ЭДО (Диадок/СБИС): договор-оферта, счёт, акт, счёт-фактура, УПД. Это российский поставщик, поэтому валютная карта и VPN не нужны. Цена за токены — 1-в-1 с прайсом провайдера по курсу ЦБ; сервисная комиссия 5% берётся только при пополнении баланса.

Работает ли официальный OpenAI SDK без патчей?

Да. Официальные openai SDK для Python и Node не требуют ни форков, ни патчей, ни обёрток — вы просто передаёте им другой base_url/baseURL и ключ (или задаёте их через переменные окружения OPENAI_BASE_URL и OPENAI_API_KEY). SDK формирует стандартный HTTP-запрос и отправляет его по указанному адресу; что Promptra совместима с форматом OpenAI — этого достаточно, чтобы всё заработало из коробки.

Сохраняются ли streaming и function calling?

Да. Streaming (флаг stream, итерация по дельтам) и function calling (tools, tool_choice, разбор tool_calls) работают в том же формате, что и у OpenAI, — менять код не нужно. Structured output через response_format тоже поддерживается там, где его поддерживает сама модель. Это и есть смысл OpenAI-совместимости: совпадает не только инициализация, но и весь протокол запросов и ответов.

Можно ли держать запасной провайдер для отказоустойчивости?

Да, и это распространённая практика. Поскольку и прямой OpenAI, и Promptra, и большинство агрегаторов используют один формат, переключение между ними — это смена base_url и ключа, в идеале вынесенных в переменную окружения. Для прода с требованием высокого аптайма можно завести резервный ключ у второго сервиса с минимальным депозитом и переключаться на него при сбое — без правки кода, одной переменной.

Если хотите перенести существующий проект на Promptra и заранее прикинуть стоимость под свой объём запросов и набор моделей — напишите команде напрямую в Telegram. Не маркетингу и не саппорту первой линии, а живому человеку: вопрос с выбором моделей, миграцией и расчётом бюджета обычно решается за один разговор.

Promptra

Готовы попробовать Promptra?

Один API-ключ ко всем флагманским LLM. Оплата на юр.лицо, цены в рублях по курсу ЦБ. Тестовые токены бесплатно.

Promptra

Готовы попробовать Promptra?

Один API-ключ ко всем флагманским LLM. Оплата на юр.лицо, цены в рублях по курсу ЦБ. Тестовые токены бесплатно.