# Ключ, тариф и баланс

> Сколько ещё может потратить API-ключ OpenCheese: GET /v1/key, /v1/plan и /v1/balance и поля их ответов. Бесплатно и без учёта в лимитах.
>
> Веб-страница: https://opencheese.dev/ru/docs/account/ · Все страницы документации: https://opencheese.dev/ru/docs.md

Три эндпоинта только для чтения показывают, сколько ещё может потратить ключ. Они принимают тот
же ключ, что и любой другой запрос, ничего не стоят и не учитываются в ваших лимитах запросов.

Каждый ответ обёрнут в `data`, и все суммы указаны в кредитах (USD). `null` означает, что лимита
нет или что окно ещё не началось.

## Ключ: GET /v1/key

```bash
curl https://api.opencheese.dev/v1/key \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

```json
{
  "data": {
    "label": "Laptop",
    "limit": 50,
    "limit_usage": 12.5,
    "limit_remaining": 37.5,
    "limit_reset": null,
    "usage": 182.4,
    "created_at": "2026-09-01T10:00:00.000Z",
    "last_used_at": "2026-10-17T09:12:00.000Z"
  }
}
```

- `limit` — лимит расходов ключа. Он ограничивает то, что ключ тратит с вашего баланса; расход по
  тарифу никогда в него не засчитывается и никогда им не блокируется.
- `limit_usage` — расходы с баланса, засчитанные в лимит с момента его последнего сброса на
  странице **API-ключи**, а `limit_remaining` — сколько осталось. Сами по себе лимиты никогда не
  сбрасываются, поэтому `limit_reset` всегда равен `null`.
- `usage` — всё, что ключ когда-либо потратил, по тарифу и с баланса.

## Тариф: GET /v1/plan

```bash
curl https://api.opencheese.dev/v1/plan \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Без тарифа ответ — `{"data": null}`. С тарифом:

```json
{
  "data": {
    "name": "Pro",
    "status": "active",
    "started_at": "2026-10-01T09:00:00.000Z",
    "expires_at": "2026-10-31T09:00:00.000Z",
    "auto_renew": true,
    "windows": {
      "five_hour": { "limit": 5, "usage": 1.2, "remaining": 3.8, "resets_at": "2026-10-17T14:00:00.000Z" },
      "weekly": { "limit": 25, "usage": 9.1, "remaining": 15.9, "resets_at": "2026-10-20T09:00:00.000Z" },
      "monthly": { "limit": 100, "usage": 40, "remaining": 60, "resets_at": "2026-10-31T09:00:00.000Z" }
    },
    "options": {
      "balance_allowed": true,
      "use_balance_on_limit": true,
      "use_balance_for_other_models": false
    }
  }
}
```

- Пятичасовое окно начинается с вашего первого оплачиваемого запроса, поэтому до этого момента его
  `resets_at` равно `null`. Месячное окно обновляется в момент `expires_at`.
- `balance_allowed` показывает, может ли тариф вообще расходовать ваш баланс.
  `use_balance_on_limit` позволяет продолжать работу за счёт баланса, когда окно исчерпано, а
  `use_balance_for_other_models` оплачивает с баланса модели, не входящие в тариф. Оба параметра —
  переключатели на странице **Обзор** в панели; если тариф не разрешает расходовать баланс, они
  равны `false`.

## Баланс: GET /v1/balance

```bash
curl https://api.opencheese.dev/v1/balance \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Эндпоинт показывает ваш баланс и расход за текущий календарный месяц (UTC) — списания по тарифу
и с баланса вместе:

```json
{
  "data": {
    "balance": 12.34,
    "month": "2026-10",
    "monthly_usage": { "tokens": 1234567, "credits": 8.9, "requests": 312 },
    "monthly_limits": { "tokens": null, "credits": null }
  }
}
```

`monthly_limits` — лимиты аккаунта, которые может установить администратор; `null` означает, что
лимита нет.

## Проверка перед долгой задачей

```bash
curl -s https://api.opencheese.dev/v1/balance \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" | jq '.data.balance'
```

Когда заканчивается баланс или когда исчерпано окно тарифа, а тариф не продолжает
работу за счёт баланса (`use_balance_on_limit`), запросы отклоняются с ошибкой
`plan_limit_reached`; подробнее — на странице [Ошибки и лимиты запросов](https://opencheese.dev/ru/docs/errors.md).