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

← Быстрый старт с APIОткрыть как Markdown

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

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

Ключ: GET /v1/key

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

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

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

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

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

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

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

{
  "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 означает, что лимита нет.

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

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

Когда заканчивается баланс или когда исчерпано окно тарифа, а тариф не продолжает работу за счёт баланса (use_balance_on_limit), запросы отклоняются с ошибкой plan_limit_reached; подробнее — на странице Ошибки и лимиты запросов.