RussiaAPI

Руководство для разработчиков

OpenAI-совместимый API: как подключить приложение к AI gateway

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

Опубликовано 6 августа 2026 · 11 минут чтения · Ключевой запрос: OpenAI-совместимый API

Важно. RussiaAPI — независимый сторонний API gateway, а не официальный сервис OpenAI, Anthropic, Google или другого производителя моделей. Совместимость относится к формату интерфейса, а не к статусу партнёрства или гарантированной доступности конкретной модели. Работайте только со своим ключом RussiaAPI; не передавайте ключи вышестоящих провайдеров, пароли, cookie или одноразовые коды.

Что даёт совместимый формат

Во многих проектах уже есть код, рассчитанный на привычную схему: базовый URL, Bearer-авторизация, endpoint для списка моделей и endpoint для сообщений. В таком случае переход на gateway обычно не требует переписывать бизнес-логику. В конфигурации меняются адрес и ключ, а выбор модели переносится в переменную окружения или настройку приложения. Это полезно, когда разработчик хочет отделить интеграционный слой от конкретного канала модели.

Однако «совместимый» не означает «идентичный во всём». У разных моделей могут отличаться лимиты, поддержка инструментов, формат ответа на некоторых endpoint и доступность в текущем каталоге. Поэтому правильный порядок такой: сначала посмотреть актуальный каталог и документы, затем проверить список, который видит конкретный ключ, и только потом включать модель в production-цепочку. Не используйте статью как список обещанных моделей.

Создайте отдельный ключ для приложения

Начните в консоли RussiaAPI с отдельного API Key для одного сервиса или окружения. Подпишите ключ понятным именем, например web-prod или support-staging, и при возможности задайте подходящие квоты. Такой подход помогает быстрее отозвать доступ при инциденте и не смешивать расходы тестов с расходами рабочей системы.

Сам ключ показывается в чувствительном виде, поэтому сохраните его в секретах развёртывания, а не в исходном коде. Для локальной разработки подойдет файл окружения, исключённый из Git. В CI/CD используйте защищённое хранилище секретов платформы. В браузерный JavaScript, мобильное приложение и публичный пример ключ помещать нельзя: оттуда его легко извлечь. Клиентское приложение должно обращаться к вашему серверу, а сервер — к API gateway.

# .env.local — файл не добавляется в Git
RUSSIAAPI_BASE_URL=https://russiaapi.com/v1
RUSSIAAPI_API_KEY=ra_your_own_key_here
RUSSIAAPI_MODEL=replace-with-a-model-from-your-catalog

Значения выше — шаблоны, а не реальные учётные данные. Подставьте ключ, созданный именно для вашего проекта, и идентификатор модели, разрешённый этому ключу. Если ключ когда-либо оказался в логе, скриншоте, issue или коммите, сразу отзовите его в консоли и выпустите новый; простого удаления строки из репозитория недостаточно.

Сначала проверьте доступный список моделей

Перед первым запросом к генерации полезно выполнить GET /v1/models. Это снижает риск ошибиться в имени модели или ожидать функцию, которая сейчас не подключена. Команда ниже запускается в терминале после того, как вы экспортировали свои переменные окружения. Она не требует ключей внешних поставщиков и не должна выводить ключ в лог.

export RUSSIAAPI_API_KEY='ra_your_own_key_here'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $RUSSIAAPI_API_KEY" \
  https://russiaapi.com/v1/models

Успешный ответ содержит данные о моделях, доступных вашему ключу. Если сервер вернул 401 или 403, проверьте, что переменная установлена, ключ активен и его права соответствуют нужной группе. Если вы получили 404, убедитесь в базовом URL и пути. Если вы увидели 429, не меняйте ключ на чужой: разберите лимит и настройте корректное ожидание, как описано в руководстве по ошибке 429.

Первый запрос через Chat Completions

После проверки каталога используйте идентификатор из ответа. Следующий пример совместим с распространённым маршрутом Chat Completions. Он работоспособен при двух явных условиях: у вас есть активный ключ RussiaAPI, а вместо YOUR_ENABLED_MODEL подставлена модель, доступная вашему ключу. Сообщение намеренно короткое, чтобы тест не создавал ненужный расход.

curl --fail-with-body --silent --show-error \
  https://russiaapi.com/v1/chat/completions \
  -H "Authorization: Bearer $RUSSIAAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ENABLED_MODEL",
    "messages": [
      {"role": "user", "content": "Ответь одним словом: готово"}
    ],
    "temperature": 0
  }'

Для серверного кода те же параметры передаются через используемый вами OpenAI-совместимый SDK: базовый URL задаётся как https://russiaapi.com/v1, а ключ считывается только на стороне сервера. Не копируйте вызов вслепую в production. Сначала добавьте тайм-аут, обработку ошибок, ограничение длины входа и журналирование без тел запросов и без заголовка авторизации.

Настройте границы до интеграции в продукт

Технически первый ответ — не конец настройки. Для каждого окружения определите, какая модель используется по умолчанию, какое время ожидания приемлемо и что происходит при ошибке. Важно не маскировать проблему бесконечными повторами или автоматической отправкой запроса на неразрешённый сервис. Повторять стоит только временные сбои по понятной политике; 4xx-ошибки конфигурации обычно требуют исправления запроса, а не повторов.

Отдельно договоритесь о лимите токенов на один запрос и на задачу. Оценка расхода на уровне приложения делает поведение более предсказуемым и уменьшает риск случайной большой генерации. Подробнее о бюджетах, ключах и измерении токенов — в статье как снизить стоимость LLM API. Если задача использует персональные данные, проведите внутреннюю оценку законности и минимизируйте данные до отправки; gateway не отменяет обязанности вашей команды.

Типичные ошибки на старте

Готовы проверить интеграцию?

Создайте собственный ключ RussiaAPI, сверяйте доступные модели в каталоге и начинайте с малого тестового запроса. Консоль помогает управлять ключами и квотами без передачи учётных данных поставщиков.

Открыть консоль и создать API Key

FAQ

RussiaAPI — официальный API OpenAI?

Нет. RussiaAPI — независимый сторонний API gateway. Упоминание OpenAI-совместимого формата описывает интерфейс интеграции, а не официальный статус, партнёрство или обещание наличия любой конкретной модели.

Нужно ли передавать ключ поставщика моделей?

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

Как выбрать модель для первого вызова?

Откройте каталог, выполните GET /v1/models своим ключом и подставьте доступный идентификатор. Перед production-трафиком проверьте качество, лимиты и нужные возможности на собственных тестовых данных.

Читайте также