Метаданные генерации и фактические списания
Фактические списания, состав стоимости и восстановление биллинга после обрыва потока с обычным или управляющим ключом.
Обновлено
GET /v1/generation
Получите метаданные завершённого запроса и фактически списанную сумму по сохранённому gen-… ID.
Авторизация
Authorization: Bearer <API_KEY> принимает обычный или управляющий ключ. Обычный ключ читает только свои запросы. Управляющий ключ читает запросы своего рабочего пространства. Для приватных изображений и видео дополнительно проверяется владелец. X-Org-Id не поддерживается.
Query-параметры
| Поле | Тип | Описание |
|---|---|---|
id | string · обязательно | От 1 до 128 символов, формат ^gen-[0-9A-Za-z-]+$. Используйте x-generation-id или provod.generation_id, а не resp-*. |
Ответ · 200
Поля объекта data:
| Поле | Тип | Описание |
|---|---|---|
id, model | string | Публичные ID запроса и модели. |
created_at | number | Unix-время в секундах. |
currency | string | Валюта расчётов. |
total_cost, usage | number | null | Фактическая сумма, null до расчёта. Два поля с одним значением. |
billing | object | Точные суммы и статус settled или pending. Схема ниже. |
num_media_prompt, num_media_completion | number | null | Количество сохранённых входных и выходных медиа, если известно. |
upstream_inference_cost | null | Себестоимость провайдера не раскрывается. |
status, origin | string · optional | Статус и источник записи, если доступны. |
generation_time | number · optional | Длительность в секундах. |
native_tokens_prompt, native_tokens_completion, native_tokens_reasoning, native_tokens_cached | number | null · optional | Зафиксированные счётчики токенов. Отсутствие не означает нулевую стоимость. |
cache_discount | number · 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 | Ошибка | Причина |
|---|---|---|
401 | Unauthorized | Отсутствующий, недействительный, отключённый, отозванный или истёкший ключ. Заголовок X-Org-Id также отклоняется. |
403 | Forbidden | Неверный тип ключа или недостаточно прав в рабочем пространстве. |
400 | Bad Request | Отсутствующий или некорректный id. |
404 | Not 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.status | settled — списание известно; 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.