Как получить API-ключ OpenRouter и подключить модели к своим проектам

OpenRouter это агрегатор моделей с единым OpenAI-совместимым API. Один ключ открывает доступ к нескольким сотням моделей от разных провайдеров. Переход с одной на другую занимает одну строку в запросе.

Что такое OpenRouter и зачем он нужен

Своих моделей OpenRouter не обучает. Сервис принимает запрос на https://openrouter.ai/api/v1/chat/completions, выбирает провайдера под указанную модель, передаёт ему запрос и возвращает ответ в формате OpenAI Chat API. Для кода разницы между DeepSeek, Anthropic и OpenAI почти нет, меняется поле model.

Прослойка закрывает несколько практических задач сразу. Не нужно заводить отдельный аккаунт и отдельный биллинг под каждого провайдера, не нужно держать пять SDK, а при ответе 5xx запрос уходит к следующему провайдеру той же модели. Схема запроса при этом одна, поэтому клиент пишется один раз.

Провайдеры выставляют свою цену за токены, а OpenRouter берёт комиссию при пополнении баланса, а не с каждого запроса.

Смысл схемы в быстрой смене моделей. Задача, на которой одна модель не справляется, часто решается соседней. Проверка гипотезы занимает минуту вместо переписывания клиента под новый SDK.

Регистрация и получение API-ключа

Аккаунт заводится на openrouter.ai. Ключи лежат на странице openrouter.ai/settings/keys, короткий адрес openrouter.ai/keys ведёт туда же. Покупать кредиты сразу не обязательно. Новому пользователю дают небольшой бесплатный запас, а модели с суффиксом :free работают и при нулевом балансе.

При создании ключа интерфейс спрашивает имя и лимит в долларах. Лимит лучше ставить на каждый ключ. Без него утечка или сорвавшийся агент может вычерпать весь баланс вместе с автопополнением.

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

Значение ключа начинается с sk-or-v1- и живёт в переменной окружения.

export OPENROUTER_API_KEY="sk-or-v1-..."

Вместо многоточия подставьте остаток строки ключа. Если ключ попал в публичный репозиторий, его отзывают на той же странице. OpenRouter участвует в GitHub secret scanning и присылает письмо, когда находит ключ в открытом коде.

Один ключ на все сервисы удобен до первого разбора расходов. Раздельные ключи с лимитами показывают, какой сервис тратит баланс, а отзыв одного ключа не останавливает остальные.

Первый запрос через curl и Python

Минимальный запрос состоит из заголовка авторизации и JSON с моделью и сообщением. В curl заголовок задаётся явно.

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash-1017",
    "messages": [
      {"role": "user", "content": "Привет. Ответь одной строкой."}
    ]
  }'

Если на счету нет кредитов, возьмите бесплатный вариант модели с суффиксом :free.

Текст ответа лежит в choices[0].message.content. Блок usage содержит число входных и выходных токенов и поле cost со стоимостью запроса.

В ответе есть id запроса, поле model и поле provider. По ним видно, кто именно обслужил вызов. Это первое, на что смотрят, когда ответы одной модели расходятся по качеству.

Кроме Authorization есть необязательные заголовки HTTP-Referer и X-OpenRouter-Title. Они нужны для атрибуции приложения в рейтингах OpenRouter и на сам запрос не влияют. Для совместимости принимается и прежнее имя X-Title. Есть ещё X-OpenRouter-Categories для категорий в маркетплейсе.

Ошибки приходят кодами. Неверный ключ возвращает ошибку авторизации, закончившиеся кредиты дают 402, а превышение частоты запросов отвечает 429. Ошибка 404 означает неверный идентификатор модели или отсутствие подходящего endpoint; текст ошибки стоит смотреть в теле ответа.

Тот же запрос на Python

На Python хватает requests, отдельный SDK не нужен.

import os
import requests

response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
    json={
        "model": "deepseek/deepseek-v4.1-flash-1017",
        "messages": [{"role": "user", "content": "Привет. Ответь одной строкой."}],
        "max_tokens": 200,
    },
    timeout=60,
)
response.raise_for_status()

data = response.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"]["cost"])

Заголовок здесь собирается вручную, без SDK.

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

Если код уже написан на SDK openai, переписывать его не нужно. Достаточно поменять base_url и передать ключ: OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"]).

Запасные модели

В запрос можно добавить массив models со списком идентификаторов. OpenRouter пробует их по порядку, если первый недоступен. С бесплатными вариантами есть особенность: переход с :free на платную модель в таком массиве тарифицируется по цене платной.

Стриминг ответа

Для чат-интерфейса включают стриминг. Достаточно "stream": true, и ответ пойдёт событиями SSE. В потоке попадаются служебные строки : OPENROUTER PROCESSING. Их нужно пропускать, иначе парсер JSON упадёт. Последний чанк перед [DONE] несёт usage.

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

Каталог открывается на openrouter.ai/models. Тот же список в машинном виде отдаёт GET https://openrouter.ai/api/v1/models. На 20 октября 2026 в нём было около 470 записей каталога, включая варианты и мультимодальные модели с картинками и видео на входе.

Идентификатор строится как провайдер/модель, к нему добавляются суффиксы. :free даёт бесплатную версию, :nitro сортирует провайдеров по скорости, :floor по цене, :exacto по надёжности вызова инструментов, :batch включает пакетную тарификацию.

Цены указаны за миллион токенов, отдельно для входных и выходных, и у одной модели они зависят от провайдера и времени. На странице deepseek/deepseek-v4.1-flash-1017 21 октября 2026 видны предложения от $0,07 до $0,30 за миллион входных токенов и от $0,50 до $1,20 за выходные; сам DeepSeek в часы низкой нагрузки берёт $0,15 и $0,60.

Посчитаем на Telegram-боте. Тысяча запросов в день по 1 500 входных и 400 выходных токенов даёт 1,5 млн входных и 0,4 млн выходных. По $0,15 и $0,60 выходит $0,47 в день, или около $14 в месяц. По базовому тарифу $0,30 и $1,20 та же нагрузка стоит $0,93 в день, около $28 в месяц.

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

Лимиты запросов и бесплатный тариф

На платных моделях OpenRouter не ставит лимит по тарифу. Ограничения приходят от провайдера, а маршрутизация сама пробует другого, если первый упёрся в потолок. Собственный 429 приходит только от защиты от DDoS.

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

У бесплатных вариантов правила другие. Им дают 20 запросов в минуту и 50 в день, а после покупки кредитов на $10 за всё время дневной потолок вырастает до 1 000. Неудачные попытки тоже считаются, и отрицательный баланс блокирует бесплатные модели до пополнения.

Модели с суффиксом :free вынесены в каталоге отдельными позициями. Есть и маршрутизатор openrouter/free, который сам выбирает свободную модель. В продакшен такое ставить рискованно: бесплатная модель может вернуть 429 с пометкой upstream_provider_shared_pool, когда общий пул провайдера занят.

Остаток кредитов и суточный лимит видны в личном кабинете на странице ключей и в разделе активности.

Как пополнить баланс и не платить посредникам

Баланс это кредиты в долларах. Пополнение идёт на странице openrouter.ai/settings/credits, вручную или автоматически, когда баланс опускается ниже заданного значения. Комиссия при покупке 5,5%, минимум $0,80. На сами запросы она не начисляется.

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

В документации перечислены банковские карты, AliPay и криптовалюта USDC. PayPal на момент статьи в списке нет, о нём говорится как о плане.

Возврат возможен в течение 24 часов с момента покупки, комиссия не возвращается. Криптоплатежи не возвращаются вовсе. Неиспользованные кредиты сервис оставляет за собой право обнулить через год после покупки.

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

Если карта не проходит, есть рублёвый вариант: Timeweb AI Gateway даёт OpenAI-совместимый API к нескольким моделям с оплатой в рублях. Базовый URL, список моделей и примеры запросов есть в документации. Подключение описано на странице сервиса.

Схема с посредником добавляет к вашим деньгам третью сторону. Человек или бот получает доступ к аккаунту либо проводит платёж через свой, и вы теряете контроль над ключами и балансом. Пополнять баланс лучше на странице Credits в своём аккаунте. Если платёж не дошёл, пишут на support@openrouter.ai.

Подключение к Telegram-боту и агентам

Для запуска понадобятся pip install aiogram aiohttp и переменная TELEGRAM_BOT_TOKEN. Ниже минимальный бот на aiogram 3, который пересылает текст в модель и отвечает в чат.

import asyncio
import os

import aiohttp
from aiogram import Bot, Dispatcher, F
from aiogram.types import Message

dp = Dispatcher()


async def ask_model(text: str) -> str:
    payload = {
        "model": "deepseek/deepseek-v4.1-flash-1017",
        "messages": [{"role": "user", "content": text}],
        "max_tokens": 800,
    }
    headers = {"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"}
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://openrouter.ai/api/v1/chat/completions",
            json=payload,
            headers=headers,
            timeout=aiohttp.ClientTimeout(total=60),
        ) as response:
            response.raise_for_status()
            data = await response.json()
    return data["choices"][0]["message"]["content"]


@dp.message(F.text)
async def on_text(message: Message) -> None:
    answer = await ask_model(message.text)
    await message.answer(answer)


async def main() -> None:
    bot = Bot(token=os.environ["TELEGRAM_BOT_TOKEN"])
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

Запрос к OpenRouter здесь обычный POST, поэтому SDK не обязателен. Бот остаётся маленьким, потому что весь обмен с моделью укладывается в один HTTP-запрос. Сборка бота с историей диалога разобрана в статье про Telegram-бота на aiogram 3 и DeepSeek.

Для агентов к запросу добавляются tools и tool_choice. OpenRouter передаёт их провайдеру, если модель умеет вызов инструментов. Модель возвращает tool_calls, приложение выполняет функцию, добавляет результат сообщением tool и повторяет запрос; фильтр по поддержке инструментов есть в каталоге моделей. Про сами инструменты есть отдельный материал про MCP-сервер.

Поле user со стабильным идентификатором конечного пользователя тоже допускается. Документация описывает его как способ ловить злоупотребления. Для бота полезно передавать непрозрачный внутренний идентификатор чата без персональных данных.

Когда OpenRouter не нужен

Локальные модели остаются вариантом, когда данные не должны покидать машину. Запрос не уходит в сеть, а цена считается по железу и электричеству. Об этом есть отдельная статья про Ollama.

Если регламент запрещает внешние API, вариант отпадает. Запрос проходит через сторонний сервис и уходит провайдеру, даже когда логирование выключено. Zero Data Retention и маршрутизация по политике провайдеров снижают риск, но не меняют саму схему.

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

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

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

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

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

Обязательно ли покупать кредиты, чтобы попробовать

Нет. Бесплатных вариантов хватает, чтобы прогнать первый запрос и сравнить пару моделей. Пятьдесят запросов в сутки это мало, но для знакомства их достаточно.

Что делать, если ключ утёк

Отозвать на странице ключей и выпустить новый. OpenRouter участвует в GitHub secret scanning, поэтому о публикации в открытом репозитории обычно приходит письмо. Лимит на ключе в этот момент уже ограничивает ущерб.

Можно ли ставить бесплатные модели в продакшен

Лимиты у них низкие, для продакшена они обычно не годятся. Общий пул провайдера может ответить 429 в самый неудачный момент. Для продакшена берут платный вариант той же модели.

Чем OpenRouter отличается от прямого доступа к API

Единый эндпоинт, один биллинг и автоматический переход на другого провайдера при ошибке. Цена та же, что у провайдера, комиссия берётся при пополнении. При прямом договоре действуют SLA и поддержка провайдера, которых у агрегатора нет.

Хранит ли OpenRouter промпты и ответы

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