# Баланс и использование API-ключа

Source: https://provod.ai/ru/docs/api-key-usage

Эти методы только для чтения используют тот же API-ключ платформы, что и запросы к моделям. Храните его на сервере и передавайте как `Authorization: Bearer ${API_KEY}`. Пространство определяется проверенным ключом; `X-Org-Id` не может выбрать другое пространство.

## GET /v1/balance

```bash
curl --fail-with-body --silent --show-error \
  "https://api.provod.ai/v1/balance" \
  -H "Authorization: Bearer ${API_KEY}"
```

Ответ `200` имеет вид:

```typescript
type Balance = {
  availableBalance: number;
  currency: string;
  reservedBalance: number;
};
```

`availableBalance` — баланс после вычета текущего резерва; `reservedBalance` — зарезервированная сумма. Валюту возвращает окружение. В окружении provod.ai это `RUB`; не пересчитывайте её в другую валюту.

## Цены для клиента

Актуальные цены provod.ai, а не внутренние расходы поставщика, публикуются в [каталоге моделей](https://provod.ai/ru/models). Для программного чтения используйте `GET https://api.provod.ai/api/models`.

Для текстовой модели каталог может содержать:

* `promptPricePer1mTokens` — цена входных токенов за 1 миллион;
* `completionPricePer1mTokens` — цена выходных токенов за 1 миллион;
* `cacheReadPricePer1mTokens` — цена чтения кэша;
* `cacheWritePricePer1mTokens`, `cacheWrite5mPricePer1mTokens`, `cacheWrite1hPricePer1mTokens` — цены записи кэша, если они настроены;
* `currency` — валюта этих цен.

Если поле цены равно `null`, отдельная цена для этой категории не опубликована. Не подставляйте туда цену поставщика и не пересчитывайте её самостоятельно.

## GET /v1/usage

```bash
curl --fail-with-body --silent --show-error \
  "https://api.provod.ai/v1/usage?range=30d" \
  -H "Authorization: Bearer ${API_KEY}"
```

`range` необязателен. По умолчанию используется `30d`; допустимые значения: `1d`, `7d`, `30d`, `365d` и `all`. Недопустимое значение даёт `400`. Ответ имеет форму:

```typescript
type Usage = {
  range: "1d" | "7d" | "30d" | "365d" | "all";
  from: string; to: string;
  summary: Summary;
  daily: DailyPoint[];
  models: ModelBreakdown[];
};
```

`Summary` содержит числовые поля `requestCount`, `successfulRequestCount`, `failedRequestCount`, `promptTokens`, `completionTokens`, `cacheReadTokens`, `cacheWriteTokens`, `cacheWrite5mTokens`, `cacheWrite1hTokens`, `totalTokens`, `estimatedCost`, `chargedAmount` и `averageDurationMs`. `DailyPoint` содержит `date`, `requestCount`, счётчики токенов, `estimatedCost` и `chargedAmount`. `ModelBreakdown` содержит `model`, `requestCount`, счётчики токенов, `estimatedCost` и `chargedAmount`.

Массив `daily` содержит дни UTC выбранного периода, включая дни без активности. Пустые суммы и массивы сохраняют эту же типизированную форму; значения-примеры не подразумеваются. Стоимости — числа в возвращённой валюте. `estimatedCost` — записанная оценка запроса; `chargedAmount` — сумма, записанная как списанная моделью использования. Ни одно поле не следует считать счётом поставщика.

Все результаты ограничены Bearer-ключом. Данные других ключей и общий разбор по ключам не возвращаются. Постраничной выдачи отдельных запросов нет.

## GET /v1/key — сведения о текущем ключе

```bash
curl --fail-with-body --silent --show-error \
  "https://api.provod.ai/v1/key" \
  -H "Authorization: Bearer ${API_KEY}"
```

Ответ обёрнут в `{ "data": ... }` и содержит:

```typescript
type CurrentKey = {
  label: string; limit: number | null; limit_reset: string | null;
  limit_remaining: number | null; usage: number; usage_daily: number;
  usage_weekly: number; usage_monthly: number;
  byok_usage: number; byok_usage_daily: number; byok_usage_weekly: number; byok_usage_monthly: number;
  include_byok_in_limit: boolean; is_free_tier: boolean;
  free_model_daily_requests: { used: number; limit: number; remaining: number };
  is_management_key: boolean; is_provisioning_key: boolean; creator_user_id: string;
  organization_id: string | null; workspace_id: string | null; expires_at: string | null;
  allowed_data_regions: string[] | null;
  rate_limit: { interval: string; requests: number; note: string } | null;
};
```

`limit` и `limit_remaining` описывают активный лимит расходов ключа, если он задан; `limit_reset` — его период (`day`, `week` или `month`). `usage*` — суммы использования этого ключа в валюте биллинга.

### Важные особенности ответа

* `free_model_daily_requests` сейчас возвращается как `{ used: 0, limit: 0, remaining: 0 }`. Проведение бесплатной квоты в этом совместимом ответе не заявляется.
* `is_free_tier` равен `false`; `byok_usage*` равны `0`; `include_byok_in_limit` и `is_provisioning_key` равны `false`; `allowed_data_regions`, `organization_id` и `rate_limit` равны `null`. Эти значения не сообщают о скрытых квотах, учёте BYOK или доступности регионов.
* Значения вроде `total_cost` в методе генерации и эти суммы использования имеют разный смысл. Ориентируйтесь на описания полей и не сравнивайте их как расходы на поставщика.

Управляющий ключ может читать собственные метаданные через `/v1/key` и допустимые метаданные генераций через `/v1/generation`. Для него недоступны `/v1/balance`, `/v1/usage` и инференс. Для биллинга используйте `/v1/credits` и `/v1/activity`; см. [матрицу доступа](/ru/docs/management-keys).

## Связанные статьи

* [Управляющие ключи и биллинг пространства](/ru/docs/management-keys)
* [Метаданные генерации](/ru/docs/generation-metadata)
* [Авторизация API](/ru/docs/authentication)

## Решение проблем


**В ответе ключа бесплатные запросы равны нулю**


Этот совместимый ответ пока не публикует измеренную бесплатную квоту. Нулевая тройка не обещает бесплатный доступ; проверяйте текущий каталог моделей и баланс пространства.


**Использование отличается от расчёта по цене модели**


`chargedAmount` — сумма для клиента, записанная Usage. Цены каталога описывают текущие тарифы и не восстанавливают историческое подтверждённое списание конкретного запроса.
