Ключ API — это пароль для программы. Чатом пользуется человек: он входит в аккаунт и нажимает кнопки. Агент или скрипт входит иначе — он предъявляет ключ в каждом запросе. Ключ привязан к вашему аккаунту, тратит с общего баланса и не заменяет пароль: зная ключ, нельзя войти в кабинет, зато можно расходовать деньги аккаунта. Отсюда и все правила обращения с ним.
Ключ создаётся в кабинете Vtop AI. В момент создания задаются две вещи, которые определяют, чем закончится утечка ключа: лимит расходов и список разрешённых моделей. Лимит — это сумма, после которой запросы перестают проходить. Список моделей — это ограничение на то, что вообще можно вызвать этим ключом. Обе проверки происходят до обращения к модели, поэтому запрещённый запрос не тратит деньги.
Значение ключа показывается один раз при создании. Скопируйте его сразу и положите туда, где ему место: в переменную окружения на сервере, в секреты CI или в менеджер паролей. Хранить ключ в коде, в репозитории или в конфигурации, которая попадает в архив вместе с проектом, — самый частый способ потерять его вместе с балансом.
Два способа передать ключ
Ключ передаётся в заголовке запроса. Шлюз принимает оба стандартных написания — выбирать нужно то, которое умеет ваш клиент:
Authorization: Bearer ВАШ_КЛЮЧ
Стандартный способ Anthropic и единственный у клиентов на формате OpenAI: так ключ отправляют Claude Code, скрипты на официальном SDK и OpenAI-совместимые инструменты.
x-api-key: ВАШ_КЛЮЧ
Формат официального SDK Anthropic и большинства сторонних агентов: Cline, Roo Code, Kilo Code, Continue, Goose, Qwen Code, OpenHands. В их интерфейсе нет поля для произвольных заголовков, поэтому другого способа они и не предлагают.
Если в запросе есть оба заголовка, побеждает Authorization — так опечатка в основном заголовке не подменяется вторым ключом незаметно.
Что проверяет шлюз по порядку
Порядок проверок объясняет большинство «непонятных» ошибок: до модели доходит только тот запрос, который прошёл три шага.
- Ключ проверяется первым — Если ключ не передан или неизвестен, запрос отклоняется сразу — до всякой работы с моделью. Ответ: 401 и тело с типом ошибки в формате запрошенного протокола.
- Потом лимит расходов — Считается сумма, уже израсходованная этим ключом. Если лимит достигнут, запрос не уходит к модели. Это ожидаемое поведение, а не сбой: так и задумано.
- Потом список моделей — Проверяется, разрешена ли запрошенная модель этому ключу. Запрещённая модель отклоняется до обращения к поставщику.
- И только затем — запрос к модели — Если все три проверки пройдены, запрос уходит к модели, а результат попадает в журнал использования с числом токенов и суммой.
Разбор ошибок
Ответ об ошибке приходит в формате того протокола, на который ушёл запрос: у Anthropic — объект с типом ошибки и сообщением, у OpenAI — объект с полем error. Ниже — что означают коды, с которыми чаще всего сталкиваются.
| Код | Когда приходит | Что делать |
|---|---|---|
| 401 | Ключ не передан, передан пустым или неизвестен | Проверьте, что заголовок доходит до шлюза: у агентов и в прокси заголовки иногда перезаписываются. Убедитесь, что ключ скопирован целиком и не обрезан пробелом. |
| 400 | Тело запроса не разобрано или не хватает обязательных полей | Шлюз требует поля model и messages. Пустая строка в model или пустой список сообщений — тоже ошибка запроса, а не ошибка ключа. |
| 403 | Лимит расходов исчерпан или модель не разрешена ключу | Поднимите лимит в кабинете или добавьте модель в список разрешённых. Для агентов это выглядит как «перестало работать», поэтому проверяйте лимит первым делом. |
| 5xx | Ошибка на стороне шлюза или поставщика модели | Повторите запрос. Если ошибка повторяется на одной модели и не повторяется на других, дело в маршруте этой модели, а не в ключе. |
Как обращаться с ключом
Правила короткие, но именно их нарушение приводит к потерям. Ключ — это доступ к балансу, и относиться к нему стоит как к банковской карте, а не как к настройке.
- Ключ живёт в переменной окружения или в секретах CI, но не в коде и не в репозитории.
- На каждый сервис — свой ключ: тогда отзыв одного не ломает остальные, а расход видно раздельно.
- Лимит расходов задаётся сразу при создании, а не «когда-нибудь потом».
- Ключ для браузера не выдаётся: фронтенд-приложение может утечь ключ любому, кто откроет исходники страницы. Обращения к API делаются с сервера.
- Ключ, который засветился в переписке, логах или скриншоте, отзывается без раздумий — создать новый дешевле, чем считать чужие запросы.
Смотрите также
Частые вопросы о ключах
Где создаётся ключ API?
В кабинете Vtop AI, в разделе API. Там же задаются лимит расходов и список разрешённых моделей, и там же ключ отзывается.
Показывается ли ключ повторно?
Значение ключа отдаётся один раз, при создании. Если вы его не сохранили, создайте новый ключ и отзовите старый — восстановить прежнее значение нельзя.
Чем ключ API отличается от пароля?
Пароль открывает кабинет, ключ — только программные запросы. По ключу нельзя войти в аккаунт и нельзя увидеть историю переписок, но можно расходовать баланс в пределах лимита.
Что такое лимит расходов?
Сумма, после которой ключ перестаёт работать. Она считается по всем запросам этого ключа. Лимит — не подписка и не списание: пока запросов нет, ничего не расходуется.
Как проверить, что ключ рабочий?
Запросите список моделей: GET /v1/models с этим ключом. Если вернулся список — ключ принят. Этот запрос ничего не стоит: обращения к модели не происходит.
Нужно ли передавать anthropic-version?
Да, если клиент говорит на Anthropic Messages API: официальные SDK отправляют этот заголовок, и шлюз его принимает. Запросам в формате OpenAI (/v1/chat/completions) он не нужен.
Можно ли пользоваться одним ключом в нескольких программах?
Да, ключ не привязан к приложению. Но тогда и лимит у них общий, и в журнале расходы будут вперемешку — для разных задач удобнее разные ключи.