Как получить ключ OpenRouter API: пошаговая инструкция

OpenRouter API-ключ — это строка вида sk-or-v1-..., которую openrouter.ai выдаёт после регистрации и которая открывает доступ к десяткам языковых моделей через единый endpoint. Чаще всего разработчик застревает на первом шаге: непонятно, с чего начать. Ниже — порядок действий, который я проверял при сборке собственных AI-агентов: от первого ключа до его ротации в продакшне.

Что такое OpenRouter и зачем нужен API-ключ?

OpenRouter — маршрутизатор LLM-запросов: одна точка входа, один ключ, а за ней — модели от Anthropic, OpenAI, Google, Meta и других провайдеров. Вместо того чтобы хранить по отдельному ключу от каждого вендора и переписывать код при смене модели, вы отправляете запросы на единый endpoint с заголовком Authorization и выбираете модель через параметр model. Ключ привязан к аккаунту: баланс и лимиты общие для всех вызовов через него, вне зависимости от выбранной модели. Для агентов, которые должны переключаться между моделями по стоимости или доступности, это особенно удобно: смена модели — это правка одной строки в конфиге, а не рефакторинг клиента. Именно поэтому настройка лимитов и ротация ключей — часть архитектуры агента, а не опциональная мелочь.

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

Регистрация и первый ключ: пошагово

Открываете openrouter.ai и нажимаете Sign In — поддерживается авторизация через Google или GitHub. После входа переходите в раздел Keys в левом боковом меню. Нажимаете Create key, в поле Name вводите читаемое имя: agent-prod, test-local, bot-tg. Название помогает потом понять, какой ключ откуда расходует кредиты — особенно когда ключей накопится несколько.

Ключ показывается один раз, сразу после создания. Если закрыли окно, не скопировав, ключ придётся удалить и создать новый: повторно OpenRouter полное значение не показывает. Сохраняйте сразу в менеджер паролей или в .env — нигде больше. На этом шаге ключ уже рабочий: проверить можно тестовым запросом к openrouter.ai/api/v1/models с заголовком Authorization: Bearer <ваш_ключ>. Пополнить баланс можно картой через раздел Credits. Минимальное пополнение — $5, транзакция обрабатывается мгновенно.

Как настроить лимиты на ключ?

При создании ключа OpenRouter предлагает задать Credit limit — денежный потолок в долларах для этого ключа. Это не ограничение запросов в секунду, а именно расходный лимит: как только траты через ключ достигают заданного значения, все запросы начинают возвращать 402. Для агентов, работающих в автоматическом режиме без постоянного надзора, лимит обязателен: один упавший цикл с ошибкой в логике способен потратить весь баланс аккаунта за минуты.

Хорошая практика — заводить отдельный ключ для каждой среды с соответствующим лимитом: продакшн получает бюджет задачи, стейджинг — символическую сумму. Лимит меняется в любой момент через кнопку Edit на странице ключа в разделе openrouter.ai/keys. После достижения потолка ключ не блокируется насовсем: достаточно поднять значение или пополнить баланс аккаунта. Отдельно стоит проверить настройку Privacy: ключи с отключённым логированием запросов не сохраняют содержимое промптов на серверах роутера — полезно для задач с конфиденциальными данными.

Ротация ключей: зачем и когда менять

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

GitHub Actions, публичные форки и CI-логи — частые источники компрометации. Процедура ротации: создаёте новый ключ с тем же лимитом, обновляете переменную окружения во всех сервисах, делаете тестовый запрос — убеждаетесь, что новый ключ возвращает 200, — и только после этого удаляете старый. Удаление без проверки роняет агента в самый неудобный момент. Если ключ утёк в публичный репозиторий, действуете в обратном порядке: сначала удаляете скомпрометированный, затем создаёте и деплоите новый.

Какие лимиты есть у OpenRouter и что делать при ошибке 429?

OpenRouter накладывает ограничения на двух уровнях. Первый — rate limit конкретной модели: каждый провайдер задаёт своё окно (запросы в минуту, токены в минуту), и роутер транслирует его напрямую. Второй — аккаунтный: исчерпан баланс или ключ упёрся в Credit limit — приходит 402. Ошибка 429 означает именно rate limit модели. Стандартное решение — экспоненциальный backoff: начальная пауза 1–2 секунды, максимум 3–4 повтора, потом логирование и алерт.

Если 429 приходит постоянно даже при небольшой нагрузке, проверьте, не выбрали ли вы модель с особо жёсткими ограничениями у провайдера. Для агентов с высокой частотой вызовов имеет смысл добавить в маршрутизацию фолбэк: OpenRouter принимает список моделей через параметр models и автоматически переключается на следующую при недоступности текущей. Подробности — в документации роутера. Обратите внимание: 429 и 402 требуют принципиально разной обработки — первый сигнализирует о временной перегрузке, второй означает, что деньги кончились.

Хранение ключей: .env и безопасность

Ключ никогда не хранится в коде напрямую — только в переменной окружения. В локальной разработке это файл .env в корне проекта: строка OPENROUTER_API_KEY=sk-or-v1-.... Файл добавляется в .gitignore до первого коммита — не после, потому что git помнит историю и удалённый файл можно восстановить из старых коммитов.

В продакшне переменная задаётся через интерфейс деплой-платформы: Dokploy, Railway, Vercel, Docker Swarm — у каждого свой раздел env-переменных. Отдельная аккуратность: никаких console.log с содержимым ключа даже в отладочном коде — вывод может уйти в логи, а логи нередко доступны шире, чем секреты. Если работаете в команде, передавать ключи через мессенджер — плохая практика: используйте общий менеджер секретов (1Password Secrets Automation, Doppler или аналог), где у каждого сотрудника свой уровень доступа. Ещё один важный момент: .env.example в репозитории должен содержать только заглушку вида OPENROUTER_API_KEY=your_key_here, а не реальный ключ.

С какими вопросами приходят к OpenRouter?

К OpenRouter приходят с тремя разными вопросами: что это за инструмент, чем он лучше альтернатив и что такое LLM-роутер в принципе. Все три в итоге приводят разработчика к одному действию: создать ключ и подключить роутер.

Тот, кто спрашивает, что такое LLM-роутер, обычно уже думает о смене одного провайдера на агрегатор. Для разработчика AI-агента это именно тот момент, когда имеет смысл разобраться с ключами, лимитами и ротацией — до того, как агент уйдёт в продакшн и ошибка 402 появится в логах ночью.

Подводные камни, которые я встретил при разработке агентов

Первое: модель, доступная сегодня, может исчезнуть завтра. Провайдеры снимают версии без предупреждения, и агент, жёстко прописывающий конкретный идентификатор модели, падает с 404. Решение — проверять список актуальных моделей через запрос к openrouter.ai/api/v1/models при старте и держать фолбэк.

Второе: OpenRouter не отправляет вебхук при исчерпании баланса. Агент, работающий ночью без мониторинга, утром оставляет стопку ошибок 402 в логах. Минимальная страховка — алерт на HTTP-статус прямо из кода агента. Третье: ключ с нулевым Credit limit работает только для бесплатных моделей; платные запросы возвращают 402 сразу, даже если на аккаунте есть деньги. Это поведение нигде явно не задокументировано и сбивает с толку при первом столкновении — но именно так роутер отделяет «демо-ключ» от полноценного. Четвёртое: если агент использует несколько ключей параллельно, следите за тем, чтобы лимиты не перекрывались — иначе при исчерпании одного ключа агент молча переключится на другой и потратит вдвое больше запланированного.

Что проверить перед запуском агента в продакшн?

Пять пунктов, которые я прохожу перед каждым деплоем. Первый: переменная OPENROUTER_API_KEY реально проброшена в окружение сервиса, а не только присутствует в локальном .env — проверяйте командой вывода переменных окружения внутри контейнера. Второй: Credit limit выставлен и соответствует бюджету задачи — не нулевой и не безлимитный. Третий: в коде агента обрабатываются 429 и 402 по-разному: rate limit требует паузы и повтора, исчерпание средств — немедленного алерта без повторов. Четвёртый: .env в .gitignore, и это проверено командой git status, а не на память. Пятый: ключ в дашборде OpenRouter назван так, чтобы по имени было понятно, какой агент и среда его используют.

Большинство разработчиков, которые только начинают работу с роутером, спотыкаются на одном из этих пяти пунктов. Добавьте к этому чеклисту мониторинг баланса хотя бы раз в неделю — и агент будет работать без неприятных сюрпризов.