Квоты и баланс

У аккаунта и API-ключа разные остатки:

• Баланс аккаунта — средства вашего кошелька, из которых оплачиваются запросы при использовании кошелька.
• Квота API-ключа — ограничение расходов конкретного ключа. Несколько ключей могут использовать один кошелёк; их квоты не складываются в баланс аккаунта.
• Безлимитный ключ не имеет собственного ограничения расходов, но не даёт бесплатных запросов или бесконечного баланса. Доступные средства и условия подписки продолжают действовать.

Баланс и расход можно посмотреть в консоли. Для автоматической проверки используйте запросы ниже.

Кэш и оплата повторного контекста

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

При подтверждённом провайдером попадании в кэш повторная часть учитывается по отдельной ставке «Кэш» выбранной модели из каталога моделей. Она не оплачивается одновременно и как обычный вход. Кэш не бесплатный; размер скидки зависит от модели и актуального тарифа.

Например, агент отправил 300 000 входных токенов, из которых 280 000 провайдер прочитал из кэша. Тогда стоимость запроса складывается из:

• 20 000 токенов по обычной входной ставке;
• 280 000 токенов по ставке чтения кэша;
• сгенерированных токенов по выходной ставке.

Если попадания в кэш нет, все 300 000 токенов оплачиваются по обычной входной ставке. Суммы за сотни запросов складываются; один раз оплаченный контекст не становится бесплатным для всей задачи.

Кэширование зависит от модели и провайдера, совпадения начала запроса и срока хранения кэша. Изменение ранних сообщений, длительная пауза или переключение провайдера могут привести к промаху. Сам факт повтора текста не гарантирует попадание в кэш или меньшую стоимость: ставка чтения может отличаться по модели и быть выше обычной входной. Создание (запись) кэша и его чтение — разные операции; создание тоже может тарифицироваться по отдельной ставке провайдера.

В OpenAI-совместимом Chat Completions ответе usage.prompt_tokens_details.cached_tokens показывает количество токенов, сообщённое провайдером как кэшированное; оно входит в общее usage.prompt_tokens, а не добавляется сверх него. В других форматах названия и состав счётчиков отличаются: например, Anthropic отдельно сообщает cache_read_input_tokens. Если провайдер не сообщает кэшированный объём, повторный текст сам по себе не подтверждает попадание. Фактическое списание проверяйте в журнале запросов консоли; счётчик контекста в агенте сам по себе не показывает стоимость.

Квота API-ключа

Для этого запроса подходит обычный ключ sk-…, которым вы обращаетесь к моделям. Адрес находится вне /v1:

curl -sS 'https://1app.ru/api/usage/token/' \
  -H 'Authorization: Bearer <ВАШ_API_KEY>'

Пример ответа для ключа с ограниченной квотой (числа условные):

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "my-client",
    "total_granted": 1000000,
    "total_used": 250000,
    "total_available": 750000,
    "unlimited_quota": false,
    "expires_at": 0
  }
}

Поле в data	Значение
total_available	Оставшаяся квота ключа
total_used	Израсходованная квота ключа
total_granted	Сумма оставшейся и израсходованной квоты
unlimited_quota	true — ограничение квоты ключа отключено
expires_at	Срок действия: Unix timestamp в секундах; 0 — без срока

Значения квот — внутренние единицы учёта, а не рубли и не количество входных или выходных токенов модели. Перевод в деньги описан ниже.

Если unlimited_quota: true, не показывайте total_available как доступный денежный остаток: это поле не ограничивает расходы такого ключа. Даже для ограниченного ключа фактическая возможность выполнять запросы зависит также от баланса аккаунта, срока действия, статуса и настроек ключа.

Баланс аккаунта через API

Для получения баланса кошелька нужен личный токен доступа (PAT, nap_…), а не модельный API-ключ sk-….

1. Войдите в раздел «Безопасность» своей учётной записи.
2. В блоке токенов доступа создайте личный токен с разрешением «Профиль / Просмотр» (profile:read). Выберите срок действия и подтвердите создание предложенным способом.
3. Скопируйте токен при создании: полный секрет показывается один раз. Используйте его только в своих доверенных скриптах.
4. Выполните запрос. Если передаёте New-Api-User, укажите ID своего аккаунта, а не ID из чужого примера:

curl -sS 'https://1app.ru/api/user/self' \
  -H 'Authorization: Bearer <ВАШ_ЛИЧНЫЙ_ТОКЕН_ДОСТУПА>' \
  -H 'New-Api-User: <ID_ВАШЕГО_АККАУНТА>'

Ответ содержит данные профиля. Поля, относящиеся к балансу (фрагмент, числа условные):

{
  "success": true,
  "data": {
    "id": 123,
    "quota": 1000000,
    "used_quota": 250000,
    "request_count": 42
  }
}

• data.quota — текущий остаток кошелька во внутренних единицах. Повторно вычитать used_quota из него не нужно.
• data.used_quota — накопленный расход аккаунта во внутренних единицах; это не остаток и не расход за выбранный период.
• data.request_count — счётчик запросов аккаунта.

Личный токен с profile:read позволяет читать профиль, а не только сумму баланса. Не вставляйте его в публичный сайт или конфигурацию стороннего AI-клиента. Для запросов к моделям продолжайте использовать обычный API-ключ.

Перевод квот в рубли

Актуальные параметры отображения доступны без авторизации:

curl -sS 'https://1app.ru/api/status'

Нужные поля находятся в data. Пример текущих настроек:

{
  "quota_per_unit": 500000,
  "quota_display_type": "CUSTOM",
  "custom_currency_symbol": "Руб.",
  "custom_currency_exchange_rate": 92
}

При quota_display_type: "CUSTOM" сумма в валюте сайта рассчитывается так:

сумма = quota / quota_per_unit × custom_currency_exchange_rate

Например, 750000 / 500000 × 92 = 138 ₽. Для баланса аккаунта подставляйте data.quota из /api/user/self; для остатка ограниченного ключа — data.total_available из /api/usage/token/.

Параметры могут меняться. Получайте их из /api/status, а не закрепляйте 92 в своём приложении. Округляйте только итоговую сумму для отображения. Если режим или валюта сайта изменились, сначала проверьте новые настройки: приведённая рублёвая формула относится к режиму CUSTOM с рублёвой валютой.

OpenAI-совместимые счётчики в клиентах

Некоторые приложения проверяют остаток по двум адресам с обычным API-ключом:

curl -sS 'https://1app.ru/v1/dashboard/billing/subscription' \
  -H 'Authorization: Bearer <ВАШ_API_KEY>'

curl -sS 'https://1app.ru/v1/dashboard/billing/usage' \
  -H 'Authorization: Bearer <ВАШ_API_KEY>'

При текущих настройках 1APP эти ответы относятся к ключу, а не к кошельку аккаунта:

• hard_limit_usd в первом ответе — общая квота (остаток плюс расход), не сам остаток.
• total_usage во втором ответе — расход, умноженный на 100.
• При текущем режиме CUSTOM числовые значения этих совместимых интерфейсов выражены в базовых единицах quota / quota_per_unit, без рублёвого множителя. Название поля или значок валюты в клиенте не гарантирует рублёвую сумму.
• Для безлимитного ключа лимит равен условному 100000000. Не используйте его для вычисления реального денежного остатка.

Для собственной интеграции используйте /api/usage/token/ для квоты ключа и /api/user/self для баланса кошелька.

Если запрос не работает

• 401 — проверьте адрес, тип токена, заголовок Authorization и действительность токена. /api/user/self не принимает обычный ключ sk-….
• 403 — проверьте разрешение profile:read у личного токена и доступность учётной записи.
• 429 — запросы слишком частые. Проверяйте остатки периодически, а не после каждого фрагмента потокового ответа; при наличии Retry-After дождитесь указанного времени.

При обработке ответа проверяйте не только HTTP-статус, но и наличие ошибки или признак успеха: у /api/usage/token/ успешный ответ содержит code: true, у /api/user/self — success: true.