Использование и биллинг

Per-request usage приходит в каждом ответе — биллите по нему с уверенностью. Снимок баланса доступен через GET /v1/dashboard/balance.

Usage в каждом запросе

Каждый ответ /v1/messages содержит объект usage с количеством токенов:

{
"usage": {
"input_tokens": 48,
"output_tokens": 92,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}

Для chat-completions те же числа возвращаются как prompt_tokens, completion_tokens и total_tokens.

Баланс ключа: GET /v1/dashboard/balance

Возвращает текущий баланс ключа. Отвечает сразу и принимает тот же ключ, что и API.

curl -H "Authorization: Bearer sk-ВАШ_КЛЮЧ" \
https://api.oneprovider.dev/v1/dashboard/balance

Ответ 200 OK:

{
"object": "balance",
"balance_usd": 54.77,
"expires_at": "2026-07-29T19:00:00Z",
"is_active": true,
"last_synced_at": "2026-06-29T19:52:00Z"
}

• balance_usd: доступный баланс ключа в долларах.
• expires_at: срок действия ключа (ISO 8601 UTC, null, если срока нет).
• is_active: false, если ключ приостановлен или отключён.
• last_synced_at: когда баланс последний раз обновлялся.

OpenAI-совместимые эндпоинты баланса

Приложения вроде NextChat и LobeChat показывают баланс по путям OpenAI. Эти пути работают с тем же ключом в Authorization: Bearer:

Ошибки: 401, если нет заголовка Authorization: Bearer или ключ неверный; 429, если превышен лимит запросов (эндпоинты баланса ограничены по IP). Баланс и расход по каждому запросу также видны в кабинете (раздел «Расход» в боте @oneprovider_robot и на app.oneprovider.dev ).

Эффективные ставки

Биллим flat за 1M токенов по ставкам с /pricing . Без множителей, минимумов, округлений. Формула:

cost = (input_tokens / 1_000_000) * rate_in
+ (output_tokens / 1_000_000) * rate_out
+ (cache_read_input_tokens / 1_000_000) * (rate_in * 0.10)
+ (cache_creation_input_tokens / 1_000_000) * (rate_in * 1.25)

• Cache reads у большинства моделей биллятся по 10% от input-ставки.
• Cache creation (первая запись cache breakpoint) у большинства моделей биллится по 125% от input-ставки.
• Множители 0.10 и 1.25 в формуле типичные: точные ставки cache read и cache write для каждой модели указаны в таблице моделей .

Когда баланс заканчивается

Когда баланс ключа доходит до нуля, запросы с ним получают 429 с error.type insufficient_balance, error.code insufficient_quota и заголовком x-should-retry: false:

HTTP/1.1 429 Too Many Requests
x-should-retry: false
Content-Type: application/json
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}

Не повторяйте запрос: проверьте баланс кабинета и лимит ключа (раздел «Ключи»), при необходимости пополните кабинет и отправьте запрос снова (как это сделать ). Остальные коды описаны в разделе Коды ошибок .

Rate-limit (429)

Слишком много запросов за короткое время дают 429 rate_limit_error. В ответе может быть заголовок Retry-After в секундах:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded; retry later"
}
}

Если Retry-After есть, ждите не меньше; если нет, повторяйте с растущей паузой. Если 429 идут постоянно, снизьте число параллельных запросов на стороне клиента. Баланс на rate-limit не списывается.

Точность per-request usage

Объекты usage из per-request суммируются ровно в фактический расход по ключу. Проверено 2026-05-08 на сэмпле в 25 845 запросов за 24ч: максимальное расхождение <$0.001 (округление на 6-м знаке). Биллите по per-request usage с уверенностью.