Ключ и расход
GET /v1/key возвращает баланс, расход, токены, число запросов и ограничения текущего ключа. Детали отдельных запросов доступны в журнале кабинета.
Этот документ описывает контракт API. При расхождениях ориентируйтесь на фактические ответы API.
Обзор API
| Эндпоинт | Описание |
|---|---|
GET /v1/key | Состояние текущего ключа |
GET /v1/key | Накопленный расход текущего ключа |
GET /v1/key | Суммарные токены и число запросов |
GET /v1/key | Доступный баланс |
Начало работы
Base URL
Используйте API Base URL, показанный в консоли Relay. В примерах ниже он обозначен как $API_BASE_URL:
export API_BASE_URL="https://relay-llm.ru"
Аутентификация
Передавайте API-ключ Relay в заголовке Authorization каждого запроса:
Authorization: Bearer YOUR_API_KEY
Храните ключ в безопасности. Не включайте его во фронтенд-код, публичные репозитории и логи. Все ключи и ID в примерах вымышлены.
Состояние ключа
Получите данные ключа, с которым отправлен запрос. Метод не принимает ID запроса.
GET /v1/key
Поля ответа
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
key_prefix | строка | Да | Префикс текущего ключа |
Пример запроса
curl "$API_BASE_URL/v1/key" \
-H "Authorization: Bearer $RELAY_API_KEY"
Пример ответа
{
"key_prefix": "sk-rly-example",
"name": "example",
"is_active": true,
"rate_limit_rpm": 120,
"balance": "0.000000",
"spent": "0.000000",
"total_input_tokens": 0,
"total_output_tokens": 0,
"request_count": 0,
"limits": {
"total": null,
"day": null,
"month": null,
"remaining": {
"total": null,
"day": null,
"month": null
}
},
"allowed_models": null
}
Поля токенов
| Поле | Описание |
|---|---|
total_input_tokens | Входные токены, не использовавшие кэш |
total_output_tokens | Токены, сгенерированные моделью |
spent | Накопленный расход ключа |
balance | Доступный баланс |
request_count | Число запросов ключа |
Необязательные ограничения возвращают null, если лимит не задан.
Получить накопленный расход
Поле spent содержит накопленный расход текущего ключа. Для отдельных запросов используйте журнал кабинета.
GET /v1/key
Ограничения ключа
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
limits.total | integer | Да | Общий лимит ключа или null |
limits.month | integer | Да | Месячный лимит ключа или null |
Метод не принимает параметры периода; для просмотра истории откройте журнал кабинета.400 invalid_request.
Пример запроса
curl "$API_BASE_URL/v1/key" \
-H "Authorization: Bearer $RELAY_API_KEY"
Пример ответа
{
"key_prefix": "sk-rly-example",
"name": "example",
"is_active": true,
"rate_limit_rpm": 120,
"balance": "0.000000",
"spent": "0.000000",
"total_input_tokens": 0,
"total_output_tokens": 0,
"request_count": 0,
"limits": {
"total": null,
"day": null,
"month": null,
"remaining": {
"total": null,
"day": null,
"month": null
}
},
"allowed_models": null
}
Получить суммарные токены
Поля total_input_tokens и total_output_tokens содержат токены текущего ключа за всё время.
GET /v1/key
Ограничения ключа
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
limits.total | integer | Да | Общий лимит ключа или null |
limits.month | integer | Да | Месячный лимит ключа или null |
Метод не принимает параметры периода; для просмотра истории откройте журнал кабинета.400 invalid_request.
Пример запроса
curl "$API_BASE_URL/v1/key" \
-H "Authorization: Bearer $RELAY_API_KEY"
Пример ответа
{
"key_prefix": "sk-rly-example",
"name": "example",
"is_active": true,
"rate_limit_rpm": 120,
"balance": "0.000000",
"spent": "0.000000",
"total_input_tokens": 0,
"total_output_tokens": 0,
"request_count": 0,
"limits": {
"total": null,
"day": null,
"month": null,
"remaining": {
"total": null,
"day": null,
"month": null
}
},
"allowed_models": null
}
Получить баланс
Поле balance содержит доступный баланс. В управляемом режиме значение может временно отсутствовать; проверяйте balance_state.
GET /v1/key
Метод не принимает параметров периода. Контекст определяется API-ключом.
Пример запроса
curl "$API_BASE_URL/v1/key" \
-H "Authorization: Bearer $RELAY_API_KEY"
Пример ответа
{
"key_prefix": "sk-rly-example",
"name": "example",
"is_active": true,
"rate_limit_rpm": 120,
"balance": "0.000000",
"spent": "0.000000",
"total_input_tokens": 0,
"total_output_tokens": 0,
"request_count": 0,
"limits": {
"total": null,
"day": null,
"month": null,
"remaining": {
"total": null,
"day": null,
"month": null
}
},
"allowed_models": null
}
Обработка ошибок
При сбое вызова тело ответа содержит стабильный код ошибки и сообщение, помогающее диагностировать проблему.
{
"error": {
"type": "invalid_api_key",
"message": "Invalid API key"
}
}
Частые коды ошибок
| HTTP-статус | error.type / error.code | Описание |
|---|---|---|
400 | invalid_request | Некорректный запрос |
401 | missing_auth_credential / 401 | Не передан API-ключ |
401 | invalid_api_key | API-ключ недействителен |
404 | not_found | Проверьте адрес метода в документации. |
429 | rate_limit_exceeded | Слишком много запросов; повторите позже |
500 | internal_error | Внутренняя ошибка сервиса |
Рекомендации
- При сверке использования и списаний используйте одинаковые
limits.totalиlimits.month, чтобы оба запроса охватывали один и тот же период. - Цены могут меняться. Для прошлых списаний используйте
amountиз исторических записей, а не пересчитывайте их по текущему прайсу. - Настройте разумные таймауты и повторы. Для ответов
429и5xxиспользуйте экспоненциальную задержку.