provod.ai / docs
API

Метаданные генерации и фактические списания

Фактические списания, состав стоимости и восстановление биллинга после обрыва потока с обычным или управляющим ключом.

Обновлено

GET /v1/generation

Получите метаданные завершённого запроса и фактически списанную сумму по сохранённому gen-… ID.

Авторизация

Authorization: Bearer <API_KEY> принимает обычный или управляющий ключ. Обычный ключ читает только свои запросы. Управляющий ключ читает запросы своего рабочего пространства. Для приватных изображений и видео дополнительно проверяется владелец. X-Org-Id не поддерживается.

Query-параметры

ПолеТипОписание
idstring · обязательноОт 1 до 128 символов, формат ^gen-[0-9A-Za-z-]+$. Используйте x-generation-id или provod.generation_id, а не resp-*.

Ответ · 200

Поля объекта data:

ПолеТипОписание
id, modelstringПубличные ID запроса и модели.
created_atnumberUnix-время в секундах.
currencystringВалюта расчётов.
total_cost, usagenumber | nullФактическая сумма, null до расчёта. Два поля с одним значением.
billingobjectТочные суммы и статус settled или pending. Схема ниже.
num_media_prompt, num_media_completionnumber | nullКоличество сохранённых входных и выходных медиа, если известно.
upstream_inference_costnullСебестоимость провайдера не раскрывается.
status, originstring · optionalСтатус и источник записи, если доступны.
generation_timenumber · optionalДлительность в секундах.
native_tokens_prompt, native_tokens_completion, native_tokens_reasoning, native_tokens_cachednumber | null · optionalЗафиксированные счётчики токенов. Отсутствие не означает нулевую стоимость.
cache_discountnumber · optionalПоле совместимости, не детализация списаний по компонентам.

Пример запроса

Замените условный ID идентификатором своего запроса.

const response = await fetch("https://api.provod.ai/v1/generation?id=gen-example-request", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());

Ошибки

HTTPОшибкаПричина
401UnauthorizedОтсутствующий, недействительный, отключённый, отозванный или истёкший ключ. Заголовок X-Org-Id также отклоняется.
403ForbiddenНеверный тип ключа или недостаточно прав в рабочем пространстве.
400Bad RequestОтсутствующий или некорректный id.
404Not FoundЗапись ещё не завершена, отсутствует или недоступна этому ключу.

Пример ошибки авторизации:

{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}

Записи об ошибках и разрывах соединения доступны после сохранения итогового результата. 404 не подтверждает отсутствие списания. Повторяйте чтение с ограниченной задержкой; не запускайте модель повторно ради получения суммы.

Пример ошибки метода:

{
  "message": "Generation not found",
  "error": "Not Found",
  "statusCode": 404
}

Фактические списания, оценки и точные суммы

Ответ 200 обёрнут в data. Поля биллинга:

type Billing = {
  status: "settled" | "pending";
  currency: string;
  usage_charge: string | null;
  guardrail_charge: string | null;
  total_charge: string | null;
};
type GenerationMoney = {
  total_cost: number | null;
  usage: number | null;
  currency: string;
  billing: Billing;
};
ПолеЗначение
billing.statussettled — списание известно; pending — доказательств завершённого расчёта пока недостаточно.
billing.currencyВалюта биллинга генерации: используйте значение ответа, а не собственную конвертацию.
billing.usage_chargeФактический клиентский USAGE_CHARGE, не стоимость поставщика и не оценка по токенам.
billing.guardrail_chargeФактический GUARDRAIL_CHARGE, связанный через запись экономики этой генерации; посторонние списания пространства исключены.
billing.total_chargeСумма известного основного и связанного защитного списаний после подтверждения.
total_cost, usageСовместимые числовые поля итоговой суммы либо null, если она неизвестна; для точного учёта используйте строки.

Все суммы внутри billing, кроме null, — десятичные строки с восемью знаками после точки в валюте ответа. Используйте десятичную арифметику, а не двоичные числа с плавающей точкой для финансовой сверки. Не исключайте защитное списание и не прибавляйте его повторно к total_charge.

Подтверждённая платная генерация

Только синтетический фрагмент: вымышленные суммы показывают формат ответа, а не реальные цены или транзакцию. Остальные метаданные опущены.

{
  "data": {
    "id": "gen-example-request",
    "total_cost": 0.0125,
    "usage": 0.0125,
    "currency": "RUB",
    "billing": {
      "status": "settled",
      "currency": "RUB",
      "usage_charge": "0.01000000",
      "guardrail_charge": "0.00250000",
      "total_charge": "0.01250000"
    }
  }
}

Отсутствие подтверждения не означает бесплатность

Синтетический объект billing для завершённого запроса без достаточных доказательств расчёта:

{
  "status": "pending",
  "currency": "RUB",
  "usage_charge": null,
  "guardrail_charge": null,
  "total_charge": null
}

Неизвестные суммы остаются null. Ни отсутствие записи списания, ни нулевая оценка не доказывают бесплатность запроса. Повторите чтение той же генерации после расчёта, а не новый запрос к модели ради получения биллинга.

Подтверждённая бесплатная генерация

Только явно подтверждённый бесплатный результат имеет статус settled и нулевые суммы. Синтетический объект billing:

{
  "status": "settled",
  "currency": "RUB",
  "usage_charge": "0.00000000",
  "guardrail_charge": "0.00000000",
  "total_charge": "0.00000000"
}

upstream_inference_cost остаётся null: внутренняя экономика поставщика не является публичным биллингом клиента. Для текстовых запросов created_at — секунды Unix, generation_time — секунды, native_tokens_* — счётчики. Счётчики медиа описывают сохранённые входы и результаты, когда они известны; неизвестные значения — null. Маски изображений и сгенерированные миниатюры не подтверждают число оплаченных результатов.

Биллинг в JSON-ответах инференса

JSON-ответы Chat Completions, Anthropic Messages и Responses содержат дополнительное поле верхнего уровня provod. Стандартные поля протокола сохраняются. Синтетический фрагмент только с расширением:

{
  "provod": {
    "generation_id": "gen-example-request",
    "billing": {
      "status": "settled",
      "currency": "RUB",
      "usage_charge": "0.01000000",
      "guardrail_charge": "0.00250000",
      "total_charge": "0.01250000"
    }
  }
}

provod.generation_id — ID для поиска. provod.billing использует те же статусы, валюту, строковые суммы с восемью знаками и семантику null, что /v1/generation. Если клиент удаляет неизвестные поля, для сохранения расширения может понадобиться исходный ответ.

Границы потока и восстановление после обрыва

Финальное сообщение биллинга содержит то же расширение provod. Читайте поток до завершающей границы протокола: причина завершения или последний текстовый токен ещё не означают подтверждённый счёт.

Chat Completions: settlement -> billing chunk.provod -> data: [DONE]
Anthropic Messages: settlement -> message_stop.provod
Responses: settlement -> response.completed.response.provod

Сервис ожидает расчёт до отправки завершающего сообщения. Chat Completions передаёт отдельный кадр биллинга перед [DONE]. В нативном Anthropic Messages поле provod находится в объекте данных самого message_stop. В Responses поле response.provod вложено в завершающее событие (response.completed при успехе либо соответствующий терминальный статус). Не прекращайте разбор до чтения этих завершающих данных. Обычные события токенов и usage не заменяют финальный объект биллинга.

Синтетическое окончание SSE Chat Completions без stream_options.include_usage. Ранние кадры токенов опущены; пустые строки разделяют события. Модель, время, ID и суммы иллюстративны, это не реальный запрос. Финальный кадр биллинга передаётся и без запроса отчётности по токенам.

data: {"id":"gen-example-request","object":"chat.completion.chunk","created":1794268800,"model":"example/model","choices":[],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15,"cost":0.0125,"currency":"RUB"},"provod":{"generation_id":"gen-example-request","billing":{"status":"settled","currency":"RUB","usage_charge":"0.01000000","guardrail_charge":"0.00250000","total_charge":"0.01250000"}}}

data: [DONE]

Синтетический завершающий кадр нативного Messages:

event: message_stop
data: {"type":"message_stop","provod":{"generation_id":"gen-example-request","billing":{"status":"settled","currency":"RUB","usage_charge":"0.01000000","guardrail_charge":"0.00250000","total_charge":"0.01250000"}}}

Синтетический фрагмент завершающего события Responses; остальные поля ответа и события опущены. Читайте response.provod, а не event.provod:

event: response.completed
data: {"type":"response.completed","response":{"id":"resp-example","status":"completed","provod":{"generation_id":"gen-example-request","billing":{"status":"settled","currency":"RUB","usage_charge":"0.01000000","guardrail_charge":"0.00250000","total_charge":"0.01250000"}}}}

Отключённый клиент не может получить финальный счёт через закрытое соединение. Сохраняйте ID генерации сразу, как он доступен. После обрыва используйте GET /v1/generation с исходным обычным ключом или допустимым управляющим ключом. Так можно сверить оплаченный финальный 499, не запуская модель повторно. 404 не доказывает отсутствие списания: проверьте ключ и пространство, затем повторите чтение после финализации с ограниченной задержкой. Не повторяйте инференс вслепую после начала вывода: это может создать второе списание.

Отчётность пространства

/v1/activity и /v1/analytics/query суммируют фактические списания, включая оплаченные ошибки. Период определяется временем списания; возвраты учитываются отдельно. Фильтры и лимиты описаны в управляющем API.

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

Стоимость в ответе API

В Chat Completions и Responses usage.cost содержит фактическое итоговое списание, usage.currency — его валюту. При незавершённом расчёте стоимость равна null. Точная сумма с восемью знаками находится в provod.billing.total_charge. Это одна сумма в разных представлениях; складывать их нельзя. Поля стоимости поставщика не выдаются за списание клиента.

В Chat Completions итоговая SSE-часть содержит usage и provod перед [DONE], даже без stream_options.include_usage. До расчёта стоимость не публикуется. Сохраните x-generation-id из заголовка сразу; в Chat он также доступен как id первых частей стрима. Responses передаёт provod.generation_id уже в начальном событии, сохраняя свой resp-* ID. После обрыва опрашивайте /v1/generation?id=... с ограниченным числом попыток и задержкой; 404 или pending не означают нулевую стоимость. Не повторяйте генерацию ради получения цены.

Доступны сумма основного списания и отдельная защитная составляющая. Точную денежную разбивку input/output/cache read/write/reasoning и дополнительных операций текущий контракт не возвращает: исторических подтверждённых составляющих нет. Счётчики токенов не заменяют эту разбивку. Последующие возвраты не изменяют первоначальную сумму запроса. Для сводных фактических расходов используйте /v1/analytics/query или /v1/activity.

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

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