К содержимому

Ключ и расход

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:

bash
export API_BASE_URL="https://relay-llm.ru"

Аутентификация

Передавайте API-ключ Relay в заголовке Authorization каждого запроса:

http
Authorization: Bearer YOUR_API_KEY

Храните ключ в безопасности. Не включайте его во фронтенд-код, публичные репозитории и логи. Все ключи и ID в примерах вымышлены.

Состояние ключа

Получите данные ключа, с которым отправлен запрос. Метод не принимает ID запроса.

http
GET /v1/key

Поля ответа

ПараметрТипОбязательныйОписание
key_prefixстрокаДаПрефикс текущего ключа

Пример запроса

bash
curl "$API_BASE_URL/v1/key" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Пример ответа

json
{
  "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 содержит накопленный расход текущего ключа. Для отдельных запросов используйте журнал кабинета.

http
GET /v1/key

Ограничения ключа

ПараметрТипОбязательныйОписание
limits.totalintegerДаОбщий лимит ключа или null
limits.monthintegerДаМесячный лимит ключа или null

Метод не принимает параметры периода; для просмотра истории откройте журнал кабинета.400 invalid_request.

Пример запроса

bash
curl "$API_BASE_URL/v1/key" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Пример ответа

json
{
  "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 содержат токены текущего ключа за всё время.

http
GET /v1/key

Ограничения ключа

ПараметрТипОбязательныйОписание
limits.totalintegerДаОбщий лимит ключа или null
limits.monthintegerДаМесячный лимит ключа или null

Метод не принимает параметры периода; для просмотра истории откройте журнал кабинета.400 invalid_request.

Пример запроса

bash
curl "$API_BASE_URL/v1/key" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Пример ответа

json
{
  "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.

http
GET /v1/key

Метод не принимает параметров периода. Контекст определяется API-ключом.

Пример запроса

bash
curl "$API_BASE_URL/v1/key" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Пример ответа

json
{
  "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
}

Обработка ошибок

При сбое вызова тело ответа содержит стабильный код ошибки и сообщение, помогающее диагностировать проблему.

json
{
  "error": {
    "type": "invalid_api_key",
    "message": "Invalid API key"
  }
}

Частые коды ошибок

HTTP-статусerror.type / error.codeОписание
400invalid_requestНекорректный запрос
401missing_auth_credential / 401Не передан API-ключ
401invalid_api_keyAPI-ключ недействителен
404not_foundПроверьте адрес метода в документации.
429rate_limit_exceededСлишком много запросов; повторите позже
500internal_errorВнутренняя ошибка сервиса

Рекомендации

  • При сверке использования и списаний используйте одинаковые limits.total и limits.month, чтобы оба запроса охватывали один и тот же период.
  • Цены могут меняться. Для прошлых списаний используйте amount из исторических записей, а не пересчитывайте их по текущему прайсу.
  • Настройте разумные таймауты и повторы. Для ответов 429 и 5xx используйте экспоненциальную задержку.
Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key