Оформление
Расходы и история запросов через API
Чтобы узнать фактическую стоимость запроса, получите запись из журнала использования: поле quota содержит учтённый расход. Счётчики usage в ответе модели показывают объём работы, но не гарантируют сумму списания 1APP.
Какой способ выбрать
| Задача | Запрос | Авторизация |
|---|---|---|
| История запросов аккаунта, фильтры и выгрузка за период | GET /api/log/self | Личный токен доступа с usage:read |
| Недавняя история одного модельного ключа | GET /api/log/token | Модельный API-ключ |
| Суммарный расход аккаунта за период | GET /api/log/self/stat | Личный токен доступа с usage:read |
| Накопленный расход и остаток квоты ключа | GET /api/usage/token/ | Модельный API-ключ |
| Остаток кошелька и накопленный расход аккаунта | GET /api/user/self | Личный токен доступа с profile:read |
| Токены конкретного ответа | usage в ответе модели | Модельный API-ключ |
Адреса /api/… находятся вне /v1. Для них используйте корень https://1app.ru, а не Base URL модельного API https://1app.ru/v1.
Ключ модели и личный токен доступа
Модельный API-ключ (sk-…) нужен для вызова моделей. Этим же ключом можно прочитать его недавнюю историю и квоту. Он не даёт доступа к журналу всего аккаунта.
Личный токен доступа (PAT, nap_…) нужен для API аккаунта:
- Откройте раздел «Безопасность» своей учётной записи.
- Создайте личный токен с разрешением
usage:readдля журнала и статистики. Для чтения баланса добавьтеprofile:read. - Выберите срок действия и подтвердите создание предложенным способом.
- Скопируйте токен: полный секрет показывается один раз.
В примерах замените <ВАШ_PAT>, <ВАШ_API_KEY> и <ID_ВАШЕГО_АККАУНТА> своими значениями. В New-Api-User указывайте ID владельца личного токена, не имя пользователя.
Храните токены в секрете
Используйте PAT только в доверенных скриптах и на своём сервере. Не вставляйте его в публичный сайт, репозиторий или конфигурацию стороннего AI-клиента. Для работы с моделями используйте отдельный модельный ключ. Не передавайте секреты в URL.
История аккаунта: расходы по каждому запросу
bash
curl -sS -G 'https://1app.ru/api/log/self' \
-H 'Authorization: Bearer <ВАШ_PAT>' \
-H 'New-Api-User: <ID_ВАШЕГО_АККАУНТА>' \
--data-urlencode 'type=2' \
--data-urlencode 'p=1' \
--data-urlencode 'page_size=100'type=2 выбирает списания за использование. Фрагмент ответа с условными данными:
json
{
"success": true,
"message": "",
"data": {
"page": 1,
"page_size": 100,
"total": 1,
"items": [
{
"id": 1,
"created_at": 1794902400,
"type": 2,
"request_id": "example-request-id",
"model_name": "example-model",
"token_name": "my-client",
"group": "default",
"quota": 1250,
"prompt_tokens": 1000,
"completion_tokens": 100,
"is_stream": false,
"use_time": 2,
"other": "{\"billing_source\":\"wallet\"}"
}
]
}
}| Поле записи | Значение |
|---|---|
request_id | Идентификатор для связи записи с HTTP-запросом |
created_at | Время записи, Unix timestamp в секундах |
quota | Расход во внутренних единицах учёта, не токены модели и не рубли |
model_name | Модель |
token_name | Имя использованного API-ключа |
group | Группа запроса |
prompt_tokens, completion_tokens | Учтённые входные и выходные токены; состав зависит от протокола и модели |
is_stream, use_time | Потоковый режим и длительность обработки в секундах |
other | JSON-строка с дополнительными деталями; для чтения её нужно отдельно разобрать как JSON |
Поле id в этой выдаче — порядковый номер, а не постоянный идентификатор операции. Не используйте его для дедупликации или связи с ответом модели.
Фильтры и выгрузка за период
К запросу можно добавить:
| Параметр | Что отбирает |
|---|---|
start_timestamp | Записи начиная с указанной секунды включительно |
end_timestamp | Записи до указанной секунды включительно |
request_id | Записи одного запроса |
token_name | Записи ключа с указанным именем |
model_name | Записи модели |
group | Записи группы |
p | Номер страницы, начиная с 1 |
page_size | Размер страницы, максимум 100 |
Например, за одни сутки UTC:
bash
curl -sS -G 'https://1app.ru/api/log/self' \
-H 'Authorization: Bearer <ВАШ_PAT>' \
-H 'New-Api-User: <ID_ВАШЕГО_АККАУНТА>' \
--data-urlencode 'type=2' \
--data-urlencode 'start_timestamp=1794873600' \
--data-urlencode 'end_timestamp=1794959999' \
--data-urlencode 'p=1' \
--data-urlencode 'page_size=100'Для выгрузки увеличивайте p, пока очередная страница не окажется пустой. Для больших объёмов разбивайте период на небольшие интервалы. Не считайте total гарантией неограниченной глубины поиска: счётчик поиска рассчитан на ограниченную выдачу.
Новые записи могут смещать страницы во время выгрузки. Используйте фиксированную верхнюю границу времени; при повторной загрузке сохраняйте тип операции и идентификатор запроса. У одного запроса или асинхронной задачи может быть несколько записей: не удаляйте их только из-за совпадения request_id.
История одного ключа без PAT
bash
curl -sS 'https://1app.ru/api/log/token' \
-H 'Authorization: Bearer <ВАШ_API_KEY>'Ответ содержит success: true и массив записей в data, не в data.items. Поля записей такие же, как в журнале аккаунта.
Этот способ возвращает только недавние записи данного ключа. Текущий лимит — до 1000 записей; пагинации и фильтров периода или request_id нет. Если нужен конкретный запрос, найдите его в массиве самостоятельно. Для регулярной выгрузки всей истории используйте журнал аккаунта с PAT.
Суммарный расход за период
bash
curl -sS -G 'https://1app.ru/api/log/self/stat' \
-H 'Authorization: Bearer <ВАШ_PAT>' \
-H 'New-Api-User: <ID_ВАШЕГО_АККАУНТА>' \
--data-urlencode 'start_timestamp=1794873600' \
--data-urlencode 'end_timestamp=1794959999'Фрагмент ответа, числа условные:
json
{
"success": true,
"data": {
"quota": 25000,
"rpm": 0,
"tpm": 0
}
}quota— сумма записей списания за выбранный период. Возвраты из неё автоматически не вычитаются.rpmиtpm— запросы и токены за последние 60 секунд, а не количество запросов и токенов за весь выбранный период.
Можно добавить фильтры token_name, model_name, group. Этот endpoint не ищет по request_id. Он считает списания; параметр type=6 не превращает его в статистику возвратов.
Накопленный расход и остатки
Для отдельного ключа:
bash
curl -sS 'https://1app.ru/api/usage/token/' \
-H 'Authorization: Bearer <ВАШ_API_KEY>'В data находятся total_used — накопленный расход, total_available — остаток квоты, total_granted — их сумма. Успешный ответ этого endpoint содержит code: true, а не success: true.
Для аккаунта, с разрешением profile:read:
bash
curl -sS 'https://1app.ru/api/user/self' \
-H 'Authorization: Bearer <ВАШ_PAT>' \
-H 'New-Api-User: <ID_ВАШЕГО_АККАУНТА>'В data находятся quota — текущий остаток кошелька, used_quota — накопленный расход, request_count — счётчик запросов. Не вычитайте used_quota из quota повторно.
Эти счётчики не заменяют журнал за выбранный период. Квота ключа — ограничение его расходов, не отдельный кошелёк. При unlimited_quota: true поле total_available не показывает реальный доступный денежный остаток. Подробнее — «Квоты и баланс».
Некоторые клиенты используют /v1/dashboard/billing/subscription и /v1/dashboard/billing/usage. Это совместимые счётчики, не история отдельных операций. Их единицы и условный лимит безлимитного ключа описаны в разделе о совместимости.
Usage в ответе модели
Обычный ответ
В /v1/chat/completions смотрите usage.prompt_tokens, usage.completion_tokens, usage.total_tokens. При наличии сведений о кэше они находятся в деталях usage.
В /v1/responses используются, в частности, usage.input_tokens и usage.output_tokens; в /v1/messages — счётчики формата Anthropic. Не складывайте счётчики разных форматов без учёта правил кэша.
Потоковый ответ Chat Completions
Добавьте к телу запроса:
json
{
"stream": true,
"stream_options": {
"include_usage": true
}
}Это фрагмент настроек, не полный запрос. Прочитайте поток до конца: итоговый usage приходит ближе к завершению. При обрыве соединения клиент может не получить итоговые счётчики; проверьте журнал.
Почему usage не равен стоимости
На стоимость влияют модель, группа, чтение и создание кэша, дополнительные услуги и способ тарификации. Некоторые модели тарифицируются не только по текстовым токенам.
Необязательное поле usage.cost, если оно есть, может содержать стоимость со стороны поставщика. Это не гарантированное списание 1APP и не гарантированная сумма в рублях. Правило относится и к нативным endpoints, например моделям принятия решений.
Как узнать стоимость конкретного ответа
- При вызове модели сохраните HTTP-заголовок
X-Oneapi-Request-Id. - Дождитесь завершения ответа, в том числе потокового.
- Найдите записи списания по этому идентификатору:
bash
curl -sS -G 'https://1app.ru/api/log/self' \
-H 'Authorization: Bearer <ВАШ_PAT>' \
-H 'New-Api-User: <ID_ВАШЕГО_АККАУНТА>' \
--data-urlencode 'type=2' \
--data-urlencode 'request_id=<ЗНАЧЕНИЕ_X_ONEAPI_REQUEST_ID>'- Прочитайте
data.items[].quotaи переведите значение в валюту сайта по формуле ниже.
Для сохранения заголовков в curl добавьте -D response-headers.txt к своему модельному запросу. Используйте ID именно из ответа модели, не из последующего запроса к журналу: каждый HTTP-запрос получает собственный идентификатор.
Поле id в JSON модели, например chatcmpl-…, не заменяет X-Oneapi-Request-Id. Не подставляйте его в фильтр журнала.
Если журнал пока пуст, повторите чтение с небольшой задержкой и ограниченным числом попыток. Пустой ответ сразу после генерации не доказывает отсутствие списания. Без PAT можно найти request_id в массиве /api/log/token, пока запись входит в недавнюю историю.
Перевод расхода в рубли
Получите параметры отображения без авторизации:
bash
curl -sS 'https://1app.ru/api/status'Для data.quota_display_type: "CUSTOM" с рублёвой валютой:
text
сумма_руб = quota / data.quota_per_unit × data.custom_currency_exchange_rateНапример, при quota_per_unit=500000 и custom_currency_exchange_rate=100 запись quota=1250 соответствует 0,25 ₽.
Получайте параметры из /api/status, а не закрепляйте курс в программе. Проверяйте режим и валюту отображения. Складывайте внутренние единицы без промежуточного округления; округляйте только итоговую денежную сумму для показа. Значения токенов модели в эту формулу не подставляют.
Возвраты, асинхронные задачи и подписки
Возвраты и окончательная стоимость задачи
Для чтения возвратов используйте /api/log/self с type=6 вместо type=2. Остальные фильтры и пагинация сохраняются. Без type журнал возвращает разные типы операций; не суммируйте все записи как расход.
Асинхронная генерация может сначала создать предварительное списание, затем дополнительное списание или возврат. Для такой задачи считайте:
text
чистый_расход = сумма quota записей type=2 − сумма quota записей type=6В записях возврата quota может быть положительной суммой возврата — вычитайте её, а не прибавляйте. Сопоставляйте операции по данным задачи, в том числе task_id в разобранном other, если поле присутствует. У поздней корректировки идентификатор запроса может отличаться от первоначального.
Дождитесь окончательного статуса задачи. Не считайте первую запись окончательной ценой и не ожидайте ровно одну запись журнала на задачу. Возврат квоты за запрос — не то же самое, что возврат банковского платежа.
Расход по подписке и по кошельку
Если в разобранном other есть billing_source, значение wallet означает кошелёк, subscription — квоту подписки. При оплате подпиской расход запроса не означает такое же уменьшение кошелька.
Для подписки могут присутствовать subscription_consumed, subscription_total, subscription_used, subscription_remain и wallet_quota_deducted. Эти дополнительные поля могут отсутствовать. Остаток подписки в старой записи — снимок на момент запроса, не текущий остаток.
Рублёвый эквивалент использованной квоты подписки не равен отдельному денежному платежу за каждый запрос. Стоимость покупки подписки и расход включённой квоты учитывайте раздельно.
Ошибки и надёжность интеграции
- 401 — проверьте тип и действительность токена, заголовок
Authorizationи адрес. Модельный ключ не заменяет PAT для/api/log/self. - 403 — проверьте разрешение
usage:readилиprofile:read, ID аккаунта и доступность учётной записи. - 429 — уменьшите частоту чтения; при наличии
Retry-Afterдождитесь указанного времени. Не опрашивайте журнал после каждого SSE-фрагмента. - HTTP 200 с ошибкой в теле — проверяйте
successу журнала, статистики и профиля,codeу/api/usage/token/. Одного HTTP-статуса недостаточно.
Не определяйте стоимость запроса разницей баланса до и после вызова: параллельные запросы, пополнения, возвраты и подписки делают такой расчёт неоднозначным. Используйте журнал и сохраняйте идентификаторы запросов вместе с собственными данными об операциях.