Аутентификация
Как работают API-ключи Half Off Dev: четыре способа передать ключ, бесплатная проверка ключа, ошибки 401 и безопасное хранение ключей.
В Half Off Dev используется один вид учётных данных: API-ключ, привязанный к вашему предоплаченному балансу. Одним и тем же ключом вызываются Claude, GPT и Gemini, а передаёте вы его в том заголовке, который уже использует ваш SDK или CLI, так что писать код аутентификации не нужно.
Создание ключа#
Ключи создаются на странице API-ключи. Каждый ключ — это ho- плюс 40 букв и цифр, и показывается он один раз. Half Off Dev хранит только хеш, поэтому потерянный ключ утерян навсегда: отзовите его и выпустите новый.
Все примеры в этой документации ожидают ключ в $HALFOFF_API_KEY:
export HALFOFF_API_KEY="ho-..."Лимиты расходов, списки разрешённых моделей и сроки действия описаны в разделе API-ключи.
Куда можно поместить ключ#
Подстраивать заголовок под Half Off Dev не нужно: каждая из четырёх форм ниже принимается на любом эндпоинте, поэтому оставьте настройки клиента по умолчанию.
| Форма | Как выглядит | Кто обычно отправляет |
|---|---|---|
| Bearer-токен | Authorization: Bearer ho-... | OpenAI SDK, Codex CLI, Claude Code через ANTHROPIC_AUTH_TOKEN, OpenAI-совместимые приложения |
Заголовок x-api-key | x-api-key: ho-... | Anthropic SDK |
Заголовок x-goog-api-key | x-goog-api-key: ho-... | Google Gen AI SDK, Gemini CLI |
Параметр запроса key | ?key=ho-... | REST-примеры Gemini |
Если в запросе указано несколько форм, Half Off Dev читает их в таком порядке и использует первую найденную: Authorization: Bearer, затем x-api-key, затем x-goog-api-key, затем ?key=.
Заголовки лучше строки запроса
URL с ключом попадает в логи прокси и историю оболочки. Используйте ?key= только тогда, когда клиент не умеет задавать заголовок.
Бесплатная проверка ключа#
Подсчёт токенов проверяет ключ и модель точно так же, как настоящий запрос, но ничего не списывает. Ответ 200 с числом input_tokens означает, что ключ действует и ему разрешено вызывать эту модель.
curl https://halfoff.dev/v1/messages/count_tokens \
-H "x-api-key: $HALFOFF_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5.5",
"messages": [{"role": "user", "content": "Is this key working?"}]
}'Публичные эндпоинты#
Каталог моделей открыт, так что проверить id и цены можно ещё до создания аккаунта. Ключ, отправленный на эти эндпоинты, игнорируется.
| Эндпоинт | Что возвращает |
|---|---|
GET /v1/models | Все модели с размером контекста, ценами и группами каналов |
GET /v1beta/models | Тот же каталог в формате Gemini |
Для всех запросов к моделям, включая подсчёт токенов, нужен ключ.
Ошибки 401#
Если ключ отсутствует, неизвестен, отозван или просрочен, вы получите 401 в формате ошибок того API, которое вы вызывали.
| Причина | Сообщение |
|---|---|
| В запросе нет ключа | Missing API key |
| Ключ неизвестен или отозван, либо аккаунт заблокирован | Invalid or revoked API key |
| Срок действия ключа истёк | This API key has expired |
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or revoked API key"}}Ключ, успешно прошедший аутентификацию, всё равно может быть отклонён из-за собственных лимитов: 403, если модели нет в списке разрешённых, 402, когда лимит расходов исчерпан, 429 при достижении лимита запросов. Эти лимиты объясняет раздел API-ключи, а все статусы перечислены в разделе Ошибки.
Безопасное обращение с ключами#
- Только на стороне сервера. API отвечает на запросы с любого origin, поэтому ключ, встроенный в веб-страницу или мобильное приложение, может быть извлечён и потрачен кем угодно. Обращайтесь к Half Off Dev из своего бэкенда.
- Никогда в репозитории. Читайте ключи из переменных окружения или менеджера секретов и добавляйте файлы
.envв.gitignore. - Отдельные ключи для каждого приложения и окружения. Утёкший ключ стейджинга не доберётся до продакшена, а Логи покажут, какой ключ что отправил.
- Ограничивайте общие ключи. Ключи для CI-задач, скриптов или коллег должны иметь лимит расходов, список разрешённых моделей и срок действия. См. API-ключи.
- Меняйте по расписанию и немедленно, когда уходит человек, у которого был ключ. Подробнее в разделе Безопасность.