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

Source: https://provod.ai/ru/docs/generation-metadata

**`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 идентификатором своего запроса.




TypeScript



Python



cURL




```typescript
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());
```



```python
import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.provod.ai/v1/generation?id=gen-example-request",
    method="GET",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
with urlopen(request) as response:
    print(json.load(response))
```



```bash
curl --fail-with-body --silent --show-error -X GET \
  "https://api.provod.ai/v1/generation?id=gen-example-request" \
  -H "Authorization: Bearer ${API_KEY}"
```



## Ошибки


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


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

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

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

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

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

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

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

```typescript
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`.

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

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

```json
{
  "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` для завершённого запроса без достаточных доказательств расчёта:

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

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

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

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

```json
{
  "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`. Стандартные поля протокола сохраняются. Синтетический фрагмент только с расширением:

```json
{
  "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`. Читайте поток до завершающей границы протокола: причина завершения или последний текстовый токен ещё не означают подтверждённый счёт.

```text
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 и суммы иллюстративны, это не реальный запрос. Финальный кадр биллинга передаётся и без запроса отчётности по токенам.

```text
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:

```text
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`:

```text
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](/ru/docs/management-keys).

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

* [Управляющие ключи и биллинг пространства](/ru/docs/management-keys)
* [Баланс и использование API-ключа](/ru/docs/api-key-usage)
* [Авторизация API](/ru/docs/authentication)

## Стоимость в ответе 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`.

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


**После обрыва генерация возвращает 404**


Проверьте точный ID, исходный обычный или допустимый управляющий ключ, пространство и владельца медиа. Повторите чтение после финализации с ограниченной задержкой. Отсутствие записи не доказывает бесплатность; не запускайте инференс повторно ради биллинга.


**Management-запрос возвращает 403**


Проверьте, что метод принимает управляющие ключи и область ключа соответствует пространству. Права сессии кабинета и Bearer-авторизация управляющего ключа различаются. Не передавайте `X-Org-Id` для переключения пространства.
