Токены и usage

Каждый ответ содержит объект `usage` со счётчиками токенов. По ним считается стоимость запроса: цены за токен лежат в каталоге моделей. Набор полей зависит от эндпоинта: три формата считают ввод по-разному. ## Chat Completions ```json "usage": { "prompt_tokens": 68, "completion_tokens": 30, "total_tokens": 98, "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0, "audio_tokens": 0, "video_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "image_tokens": 0 } } ``` | Поле | Что считает | |---|---| | `prompt_tokens` | Весь ввод, включая кэшированные токены | | `completion_tokens` | Весь вывод, включая рассуждения | | `total_tokens` | Сумма ввода и вывода | | `prompt_tokens_details.cached_tokens` | Часть ввода, прочитанная из кэша, тарифицируется дешевле | | `prompt_tokens_details.cache_write_tokens` | Часть ввода, записанная в кэш | | `completion_tokens_details.reasoning_tokens` | Часть вывода, ушедшая на рассуждения | Вложенные поля это **части** соответствующего итога, а не добавка к нему. Некэшированный ввод считается как `prompt_tokens - cached_tokens - cache_write_tokens`. ## Messages ```json "usage": { "input_tokens": 65, "output_tokens": 137, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 }, "output_tokens_details": { "thinking_tokens": 30 } } ``` Здесь действует соглашение Anthropic: `input_tokens` это **только некэшированный** ввод, а кэш идёт отдельными полями. Полный ввод считается сложением: ``` всего ввода = input_tokens + cache_read_input_tokens + cache_creation_input_tokens ``` `cache_creation` разбивает запись в кэш по времени жизни (5 минут и 1 час), потому что тарифы у них разные. См. [Кэширование промптов](/router/prompt-caching/). Рассуждения лежат в `output_tokens_details.thinking_tokens` и входят в `output_tokens`, см. [Reasoning](/router/reasoning/). Если запрос искал в интернете, появляется блок `server_tool_use` со счётчиком выполненных поисков. Каждый оплачивается отдельно от токенов, см. [Веб-поиск](/router/web-search/): ```json "server_tool_use": { "web_search_requests": 1, "web_fetch_requests": 0 } ``` Тот же блок с тем же смыслом приходит и в `usage` на chat completions, и в `usage` на responses: счётчик один на все три поверхности, чтобы клиенту не приходилось читать его тремя способами. ## Responses ```json "usage": { "input_tokens": 14, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 6, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 20 } ``` `input_tokens` здесь включает кэшированную часть, как в Chat Completions, а `cached_tokens` показывает, сколько из них прочитано из кэша. Токены рассуждения лежат в `output_tokens_details.reasoning_tokens` и входят в `output_tokens`. ## Стриминг При `"stream": true` счётчики приходят в конце, отдельного запроса за ними не нужно: - `/v1/chat/completions`: последний чанк перед `data: [DONE]` несёт `usage`; - `/v1/messages`: событие `message_delta` несёт `usage` с итоговыми значениями. В `message_start` счётчики ещё нулевые; - `/v1/responses`: завершающее событие (`response.completed` или `response.incomplete`) несёт итоговый `usage` внутри `response`. Если клиент разорвал соединение посередине, генерация всё равно оплачивается: провайдер её выполнил. Поэтому обрыв не способ отменить запрос. ## Оценка стоимости Цены за один токен лежат в `pricing` каждой модели в `GET /v1/models` и соответствуют вашему тарифу: ```json "pricing": { "prompt": "0.000002", "completion": "0.00001", "input_cache_read": "0.0000002", "input_cache_write": "0.0000025" } ``` Стоимость запроса это сумма произведений: некэшированный ввод на `prompt`, чтение из кэша на `input_cache_read`, запись в кэш на `input_cache_write`, вывод на `completion`. У части моделей есть отдельные строки для рассуждений (`internal_reasoning`), изображений, аудио и записи кэша на час (`input_cache_write_1h`). [Веб-поиск](/router/web-search/), выполненный роутером, это другое: он тарифицируется по своей цене, которой в каталоге моделей нет, и добавляется к сумме сверху. Найденное попадает во ввод следующего шага, поэтому запрос с поиском дорожает дважды: самим поиском и выросшим числом входных токенов. Само поле стоимости в ответе не возвращается: считайте по `usage` и каталогу либо смотрите фактические списания в личном кабинете. ## Что учитывать - **Токены не равны символам.** Русский текст в среднем дороже английского при равной длине: разбиение на токены зависит от модели. - **Вложения тоже токены.** Изображение или PDF превращаются в токены ввода по правилам модели, см. [Изображения и PDF](/router/attachments/). - **Инструменты увеличивают ввод.** Определения `tools` передаются в каждом запросе цикла и считаются как часть промпта. - **Кэш меняет структуру, а не размер ввода.** Токены никуда не исчезают, просто часть из них тарифицируется по цене чтения из кэша. - **Редко блок `usage` не приходит совсем.** Так бывает, когда генерация упирается в очень маленький `max_output_tokens` и модель не успевает выдать ни одного видимого токена. Такой запрос не тарифицируется: платить не за что, и с вас ничего не списывается. В истории расхода его тоже не будет, поэтому искать там нечего. Достаточный `max_output_tokens` убирает этот случай.

Каждый ответ содержит объект usage со счётчиками токенов. По ним считается стоимость запроса: цены за токен лежат в каталоге моделей. Набор полей зависит от эндпоинта: три формата считают ввод по-разному.

Chat Completions

"usage": {
  "prompt_tokens": 68,
  "completion_tokens": 30,
  "total_tokens": 98,
  "prompt_tokens_details": {
    "cached_tokens": 0,
    "cache_write_tokens": 0,
    "audio_tokens": 0,
    "video_tokens": 0
  },
  "completion_tokens_details": {
    "reasoning_tokens": 0,
    "audio_tokens": 0,
    "image_tokens": 0
  }
}

Поле	Что считает
`prompt_tokens`	Весь ввод, включая кэшированные токены
`completion_tokens`	Весь вывод, включая рассуждения
`total_tokens`	Сумма ввода и вывода
`prompt_tokens_details.cached_tokens`	Часть ввода, прочитанная из кэша, тарифицируется дешевле
`prompt_tokens_details.cache_write_tokens`	Часть ввода, записанная в кэш
`completion_tokens_details.reasoning_tokens`	Часть вывода, ушедшая на рассуждения

Вложенные поля это части соответствующего итога, а не добавка к нему. Некэшированный ввод считается как prompt_tokens - cached_tokens - cache_write_tokens.

Messages

"usage": {
  "input_tokens": 65,
  "output_tokens": 137,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 },
  "output_tokens_details": { "thinking_tokens": 30 }
}

Здесь действует соглашение Anthropic: input_tokens это только некэшированный ввод, а кэш идёт отдельными полями. Полный ввод считается сложением:

всего ввода = input_tokens + cache_read_input_tokens + cache_creation_input_tokens

cache_creation разбивает запись в кэш по времени жизни (5 минут и 1 час), потому что тарифы у них разные. См. Кэширование промптов. Рассуждения лежат в output_tokens_details.thinking_tokens и входят в output_tokens, см. Reasoning.

Если запрос искал в интернете, появляется блок server_tool_use со счётчиком выполненных поисков. Каждый оплачивается отдельно от токенов, см. Веб-поиск:

"server_tool_use": { "web_search_requests": 1, "web_fetch_requests": 0 }

Тот же блок с тем же смыслом приходит и в usage на chat completions, и в usage на responses: счётчик один на все три поверхности, чтобы клиенту не приходилось читать его тремя способами.

Responses

"usage": {
  "input_tokens": 14,
  "input_tokens_details": { "cached_tokens": 0 },
  "output_tokens": 6,
  "output_tokens_details": { "reasoning_tokens": 0 },
  "total_tokens": 20
}

input_tokens здесь включает кэшированную часть, как в Chat Completions, а cached_tokens показывает, сколько из них прочитано из кэша. Токены рассуждения лежат в output_tokens_details.reasoning_tokens и входят в output_tokens.

Стриминг

При "stream": true счётчики приходят в конце, отдельного запроса за ними не нужно:

/v1/chat/completions: последний чанк перед data: [DONE] несёт usage;
/v1/messages: событие message_delta несёт usage с итоговыми значениями. В message_start счётчики ещё нулевые;
/v1/responses: завершающее событие (response.completed или response.incomplete) несёт итоговый usage внутри response.

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

Оценка стоимости

Цены за один токен лежат в pricing каждой модели в GET /v1/models и соответствуют вашему тарифу:

"pricing": {
  "prompt": "0.000002",
  "completion": "0.00001",
  "input_cache_read": "0.0000002",
  "input_cache_write": "0.0000025"
}

Стоимость запроса это сумма произведений: некэшированный ввод на prompt, чтение из кэша на input_cache_read, запись в кэш на input_cache_write, вывод на completion. У части моделей есть отдельные строки для рассуждений (internal_reasoning), изображений, аудио и записи кэша на час (input_cache_write_1h).

Веб-поиск, выполненный роутером, это другое: он тарифицируется по своей цене, которой в каталоге моделей нет, и добавляется к сумме сверху. Найденное попадает во ввод следующего шага, поэтому запрос с поиском дорожает дважды: самим поиском и выросшим числом входных токенов.

Само поле стоимости в ответе не возвращается: считайте по usage и каталогу либо смотрите фактические списания в личном кабинете.

Что учитывать

Токены не равны символам. Русский текст в среднем дороже английского при равной длине: разбиение на токены зависит от модели.
Вложения тоже токены. Изображение или PDF превращаются в токены ввода по правилам модели, см. Изображения и PDF.
Инструменты увеличивают ввод. Определения tools передаются в каждом запросе цикла и считаются как часть промпта.
Кэш меняет структуру, а не размер ввода. Токены никуда не исчезают, просто часть из них тарифицируется по цене чтения из кэша.
Редко блок usage не приходит совсем. Так бывает, когда генерация упирается в очень маленький max_output_tokens и модель не успевает выдать ни одного видимого токена. Такой запрос не тарифицируется: платить не за что, и с вас ничего не списывается. В истории расхода его тоже не будет, поэтому искать там нечего. Достаточный max_output_tokens убирает этот случай.