provod.ai / docs
API

Баланс и использование API-ключа

Баланс, итоги использования и лимиты текущего API-ключа.

Обновлено

Эти методы только для чтения используют тот же API-ключ платформы, что и запросы к моделям. Храните его на сервере и передавайте как Authorization: Bearer ${API_KEY}. Пространство определяется проверенным ключом; X-Org-Id не может выбрать другое пространство.

GET /v1/balance

Terminal
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

Terminal
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 — сведения о текущем ключе

Terminal
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; см. матрицу доступа.

Связанные статьи

Решение проблем

На этой странице