Баланс и использование API-ключа
Баланс, итоги использования и лимиты текущего API-ключа.
Обновлено
Эти методы только для чтения используют тот же API-ключ платформы, что и запросы к моделям. Храните его на сервере и передавайте как Authorization: Bearer ${API_KEY}. Пространство определяется проверенным ключом; X-Org-Id не может выбрать другое пространство.
GET /v1/balance
curl --fail-with-body --silent --show-error \
"https://api.provod.ai/v1/balance" \
-H "Authorization: Bearer ${API_KEY}"Ответ 200 имеет вид:
type Balance = {
availableBalance: number;
currency: string;
reservedBalance: number;
};availableBalance — баланс после вычета текущего резерва; reservedBalance — зарезервированная сумма. Валюту возвращает окружение. В окружении provod.ai это RUB; не пересчитывайте её в другую валюту.
Цены для клиента
Актуальные цены provod.ai, а не внутренние расходы поставщика, публикуются в каталоге моделей. Для программного чтения используйте GET https://api.provod.ai/api/models.
Для текстовой модели каталог может содержать:
promptPricePer1mTokens— цена входных токенов за 1 миллион;completionPricePer1mTokens— цена выходных токенов за 1 миллион;cacheReadPricePer1mTokens— цена чтения кэша;cacheWritePricePer1mTokens,cacheWrite5mPricePer1mTokens,cacheWrite1hPricePer1mTokens— цены записи кэша, если они настроены;currency— валюта этих цен.
Если поле цены равно null, отдельная цена для этой категории не опубликована. Не подставляйте туда цену поставщика и не пересчитывайте её самостоятельно.
GET /v1/usage
curl --fail-with-body --silent --show-error \
"https://api.provod.ai/v1/usage?range=30d" \
-H "Authorization: Bearer ${API_KEY}"range необязателен. По умолчанию используется 30d; допустимые значения: 1d, 7d, 30d, 365d и all. Недопустимое значение даёт 400. Ответ имеет форму:
type Usage = {
range: "1d" | "7d" | "30d" | "365d" | "all";
from: string; to: string;
summary: Summary;
daily: DailyPoint[];
models: ModelBreakdown[];
};Summary содержит числовые поля requestCount, successfulRequestCount, failedRequestCount, promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens, cacheWrite5mTokens, cacheWrite1hTokens, totalTokens, estimatedCost, chargedAmount и averageDurationMs. DailyPoint содержит date, requestCount, счётчики токенов, estimatedCost и chargedAmount. ModelBreakdown содержит model, requestCount, счётчики токенов, estimatedCost и chargedAmount.
Массив daily содержит дни UTC выбранного периода, включая дни без активности. Пустые суммы и массивы сохраняют эту же типизированную форму; значения-примеры не подразумеваются. Стоимости — числа в возвращённой валюте. estimatedCost — записанная оценка запроса; chargedAmount — сумма, записанная как списанная моделью использования. Ни одно поле не следует считать счётом поставщика.
Все результаты ограничены Bearer-ключом. Данные других ключей и общий разбор по ключам не возвращаются. Постраничной выдачи отдельных запросов нет.
GET /v1/key — сведения о текущем ключе
curl --fail-with-body --silent --show-error \
"https://api.provod.ai/v1/key" \
-H "Authorization: Bearer ${API_KEY}"Ответ обёрнут в { "data": ... } и содержит:
type CurrentKey = {
label: string; limit: number | null; limit_reset: string | null;
limit_remaining: number | null; usage: number; usage_daily: number;
usage_weekly: number; usage_monthly: number;
byok_usage: number; byok_usage_daily: number; byok_usage_weekly: number; byok_usage_monthly: number;
include_byok_in_limit: boolean; is_free_tier: boolean;
free_model_daily_requests: { used: number; limit: number; remaining: number };
is_management_key: boolean; is_provisioning_key: boolean; creator_user_id: string;
organization_id: string | null; workspace_id: string | null; expires_at: string | null;
allowed_data_regions: string[] | null;
rate_limit: { interval: string; requests: number; note: string } | null;
};limit и limit_remaining описывают активный лимит расходов ключа, если он задан; limit_reset — его период (day, week или month). usage* — суммы использования этого ключа в валюте биллинга.
Важные особенности ответа
free_model_daily_requestsсейчас возвращается как{ used: 0, limit: 0, remaining: 0 }. Проведение бесплатной квоты в этом совместимом ответе не заявляется.is_free_tierравенfalse;byok_usage*равны0;include_byok_in_limitиis_provisioning_keyравныfalse;allowed_data_regions,organization_idиrate_limitравныnull. Эти значения не сообщают о скрытых квотах, учёте BYOK или доступности регионов.- Значения вроде
total_costв методе генерации и эти суммы использования имеют разный смысл. Ориентируйтесь на описания полей и не сравнивайте их как расходы на поставщика.
Управляющий ключ может читать собственные метаданные через /v1/key и допустимые метаданные генераций через /v1/generation. Для него недоступны /v1/balance, /v1/usage и инференс. Для биллинга используйте /v1/credits и /v1/activity; см. матрицу доступа.