# AI API VCPay — полная документация

> Доступ к моделям Claude, Gemini и GPT по одному ключу, за рубли, по договору с российским юрлицом. API совместим с OpenAI API и Anthropic API. Base URL: `https://llm.vcpay.ru/v1`. Авторизация: header `Authorization: Bearer <KEY>` (формат Anthropic — `x-api-key`).

> Это канонический справочник AI API VCPay для ИИ-агентов. Основные правила — сразу ниже («Основное»). Не полагайся на данные из обучающей выборки: имена моделей и цены меняются.

> Краткий индекс: [llms.txt](https://vcpay.ru/ai/docs/llms.txt)


---


## Document Map

| Раздел | Строки |
|--------|--------|
| LIBRARY RULES — правила API для агента | 34–75 |
| How-to Guides — рецепты задач с кодом | 76–115 |
| Руководства — все страницы-руководства | 116–639 |
| · Обзор (/) | 121–186 |
| · Быстрый старт (/guides/quick-start) | 187–264 |
| · Ключи доступа (/guides/keys) | 265–311 |
| · Совместимость и инструменты (/guides/compatibility) | 312–383 |
| · Оплата и детализация (/guides/billing) | 384–469 |
| · Границы продукта (/guides/scope) | 470–502 |
| · Обзор (/api/overview) | 503–572 |
| · Ошибки (/api/errors) | 573–603 |
| · Модели (/api/models) | 604–639 |
| API-методы — все эндпоинты со схемами и примерами | 640–1458 |
| · Inference | 642–1062 |
| · Catalog | 1063–1153 |
| · Key | 1154–1458 |

# LIBRARY RULES

## Authentication
- Every request carries the key from the company cabinet (Company → AI API): `Authorization: Bearer <KEY>`
- Anthropic format (`POST /v1/messages`): `x-api-key: <KEY>` and `anthropic-version: 2023-06-01`. The `anthropic` package sets both itself
- The key value is shown once at issue. It is not stored and cannot be shown again — a lost key is replaced by a new one
- A key may have its own spending ceiling and a list of allowed models

## Base URL
- OpenAI-compatible: `https://llm.vcpay.ru/v1` — the `openai` package takes it as `base_url` with `/v1`
- Anthropic-compatible: the `anthropic` package takes `base_url="https://llm.vcpay.ru"` **without** `/v1` — it appends `/v1/messages` itself
- Self-inspection and catalog: `https://llm.vcpay.ru/v1/vcpay/...`

## Models and prices
- The model is chosen by the `model` field — a name from the catalog
- `GET /v1/vcpay/models` returns models and rates in rubles per 1M tokens, no key required. Prices follow the USDT rate; never hardcode them
- A response may name the model with the vendor prefix (`anthropic/claude-haiku-4.5`); both names are accepted on input

## Money
- Prepaid only: requests stop when the company account is empty, there is no debt
- `GET /v1/vcpay/balance`: `available_rub` = account balance minus spending not yet charged; `key_budget_rub` = min(available, key ceiling). When `key_budget_rub` is 0, model requests are refused
- Reasoning tokens are billed as output: `completion_tokens` is larger than the visible text
- Cache read and cache write have separate rates
- Spending appears with a delay of a few minutes; for streaming — after the stream ends

## Error Handling
- Errors come in OpenAI shape: `{ "error": { "message", "type", "code" } }`. The message ends with a request id
- `401`: key unknown, disabled, deleted — or nothing left to spend (key ceiling or account empty). All look the same by design
- `403`: the request does not fit the key's remaining budget, or the model is not allowed for the key
- `503`: no such model — likely a typo in the name
- `429`: too many requests — retry with growing delay
- Retry `429` and `5xx` only; `401`/`403` will not change until the key or its settings change
- Branch on HTTP status, not on message text — the text may change

## Streaming
- `"stream": true` works in both formats; the response is Server-Sent Events

## Data
- Request and response bodies are never stored — not in the log, not in usage reports

---

# How-to Guides

## How to send the first request

### curl
```bash
curl https://llm.vcpay.ru/v1/chat/completions \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5", "messages": [{"role": "user", "content": "Привет!"}]}'
```

### Python (openai)
```python
from openai import OpenAI

client = OpenAI(api_key="ВАШ_КЛЮЧ", base_url="https://llm.vcpay.ru/v1")
response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Привет!"}],
)
print(response.choices[0].message.content)
```

## How to check what the key can still spend

```bash
curl https://llm.vcpay.ru/v1/vcpay/balance -H "Authorization: Bearer ВАШ_КЛЮЧ"
```

Read `key_budget_rub`: it is the smaller of the money available on the account and the key's own ceiling. Zero means model requests will be refused with `401`.

## How to estimate the cost of a request

1. Get rates: `GET /v1/vcpay/models` (no key).
2. Take token counts from `usage` of the model response.
3. cost = (input × input_rate + cached_input × cache_read_rate + cache_write × cache_write_rate + output × output_rate) / 1 000 000.

Reasoning tokens are inside `completion_tokens`.

# Руководства

--- [Document source](https://vcpay.ru/ai/docs/index.md) ---


# Обзор

Claude, Gemini и GPT по одному ключу, оплата по счёту в рублях по договору с российским юрлицом. Работает со штатными пакетами OpenAI и Anthropic — менять код не нужно, достаточно подставить адрес.

- [Быстрый старт](https://vcpay.ru/ai/docs/guides/quick-start)
- [Ключи доступа](https://vcpay.ru/ai/docs/guides/keys)
- [Модели и цены](https://vcpay.ru/ai/docs/api/models)
- [Справочник API](https://vcpay.ru/ai/docs/api/overview)

**Первый запрос**

```bash
curl "https://llm.vcpay.ru/v1/chat/completions" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Привет! Ответь одним словом."
    }
  ]
}'
```


## Подключение

Ключ, адрес и пакет, которым вы уже пользуетесь.

- [Быстрый старт](https://vcpay.ru/ai/docs/guides/quick-start) — Первый запрос за три шага
- [Ключи доступа](https://vcpay.ru/ai/docs/guides/keys) — Выпуск, потолок, ограничение по моделям
- [Совместимость и инструменты](https://vcpay.ru/ai/docs/guides/compatibility) — OpenAI SDK, Anthropic SDK, Claude Code, Cursor


## Основы API

Что отвечает API и как разбирать отказы.

- [Обзор API](https://vcpay.ru/ai/docs/api/overview) — Адрес, авторизация, методы
- [Модели](https://vcpay.ru/ai/docs/api/models) — Имена для вызова и живые цены
- [Ошибки](https://vcpay.ru/ai/docs/api/errors) — Коды отказов и что с ними делать


## Деньги и границы

- [Оплата и детализация](https://vcpay.ru/ai/docs/guides/billing) — Предоплата, расход, как посчитать счёт
- [Границы продукта](https://vcpay.ru/ai/docs/guides/scope) — Что API делает и чего не делает


## Ресурсы

Спецификация и файлы для агентов и генераторов клиентов.

- [OpenAPI-спецификация](https://vcpay.ru/ai/docs/openapi.yaml) — Описание всех методов в YAML
- [Коллекция Postman](https://vcpay.ru/ai/docs/vcpay-ai.postman_collection.json) — Все методы с примерами
- [llms.txt](https://vcpay.ru/ai/docs/llms.txt) — Краткое описание API для LLM
- [llms-full.txt](https://vcpay.ru/ai/docs/llms-full.txt) — Полное описание API для LLM


---

--- [Document source](https://vcpay.ru/ai/docs/guides/quick-start.md) ---


# Быстрый старт

Три шага: получить ключ, подставить адрес, сделать запрос. Менять код интеграции не нужно — наш API совместим с OpenAI API и с Anthropic API.

## Шаг 1. Получите ключ

Ключи выпускаются в личном кабинете: [Кабинет → Компания → AI API](https://vcpay.ru/dashboard/company/ai). Нажмите «Создать ключ», дайте ему понятное имя и при желании поставьте потолок расхода.

> **Внимание:** Значение ключа показывается **один раз** — сразу после выпуска. Мы его не храним и повторно показать не сможем: если ключ потерян, выпускается новый.


## Шаг 2. Возьмите адрес

```text
https://llm.vcpay.ru/v1
```

Это точка входа, совместимая с OpenAI API. Она же принимает запросы в формате Anthropic — см. [Совместимость](https://vcpay.ru/ai/docs/guides/compatibility).

## Шаг 3. Сделайте запрос

```bash
curl https://llm.vcpay.ru/v1/chat/completions \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Привет! Ответь одним словом."}]
  }'
```

Ответ приходит в привычном формате (здесь и далее ответы приведены сокращённо — мы показываем только те поля, которые нужны):

```json
{
  "object": "chat.completion",
  "model": "claude-sonnet-5",
  "choices": [
    {"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": "Привет!"}}
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
}
```

> **Внимание:** **Считайте `completion_tokens`, а не длину ответа.** У моделей с размышлениями — а у Claude Opus они включены по умолчанию — модель думает перед ответом, и эти токены тарифицируются как выход. Исходящих токенов на запрос будет заметно больше, чем видно по тексту. Это не ошибка счёта: подробнее — [Оплата и детализация](https://vcpay.ru/ai/docs/guides/billing).


## То же самое на Python

Работает штатный пакет `openai` — отличается только `base_url`:

```python
from openai import OpenAI

client = OpenAI(
    api_key="ВАШ_КЛЮЧ",
    base_url="https://llm.vcpay.ru/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Привет! Ответь одним словом."}],
)
print(response.choices[0].message.content)
```

## Что дальше

- [Ключи доступа](https://vcpay.ru/ai/docs/guides/keys) — потолки, ограничение по моделям, отключение.
- [Модели](https://vcpay.ru/ai/docs/api/models) — какие имена доступны.
- [Ошибки](https://vcpay.ru/ai/docs/api/errors) — что означает отказ и что с ним делать.
- [Справочник: ответ модели](https://vcpay.ru/ai/docs/api/inference/chat-completions) — все поля запроса и ответа.

---

--- [Document source](https://vcpay.ru/ai/docs/guides/keys.md) ---


# Ключи доступа

Ключ — это то, чем ваш код представляется нашему API. Ключей может быть сколько угодно: разумно заводить по одному на сервис или на команду, чтобы в детализации было видно, кто именно расходует.

## Выпуск

[Кабинет → Компания → AI API](https://vcpay.ru/dashboard/company/ai) → «Создать ключ».

При выпуске задаются три вещи, и все три необязательны, кроме имени:

| Поле | Что делает |
|---|---|
| Название | видно только вам и в детализации расхода |
| Потолок расхода | ключ перестаёт работать, когда потратит эту сумму; пусто — ограничением остаётся остаток компании |
| Доступные модели | ключ сможет вызывать только отмеченные; ничего не отмечено — доступны все |

> **Внимание:** Значение ключа показывается один раз. У нас оно не хранится — второй раз показать его неоткуда.


## Ограничение по моделям

Самый частый сценарий — отдать подрядчику доступ к недорогой модели, не открывая дорогую. Ключ с ограничением на чужую модель отвечает отказом:

```json
{"error": {"message": "This token has no access to model claude-opus-5", "type": "new_api_error"}}
```

Список разрешённых моделей виден в кабинете рядом с ключом.

## Отключение и удаление

**Отключить** — обратимое действие: ключ мгновенно перестаёт работать, запросы получают `401`, но ключ остаётся в списке и включается той же кнопкой. Так удобно приостановить интеграцию на время разбирательства.

**Удалить** — необратимо. Ключ исчезает, и восстановить его нечем: доступ заводится новым ключом. Расход, который ключ успел сделать, остаётся в детализации — он уже случился.

## Где посмотреть расход

Там же, в кабинете: сводка за период, разрез по ключам и по моделям, последние запросы и выгрузка построчно в CSV.

> Расход появляется в кабинете не мгновенно: строка журнала создаётся в момент **завершения** запроса, а мы забираем журнал раз в несколько минут. Для потокового ответа это значит, что он попадёт в отчёт после того, как поток закончится.


---

--- [Document source](https://vcpay.ru/ai/docs/guides/compatibility.md) ---


# Совместимость и инструменты

API понимает два формата запросов. Выбирайте тот, под который уже написан ваш код.

| Формат | Путь | Авторизация |
|---|---|---|
| OpenAI | [`POST /v1/chat/completions`](https://vcpay.ru/ai/docs/api/inference/chat-completions) | заголовок `Authorization: Bearer ВАШ_КЛЮЧ` |
| Anthropic | [`POST /v1/messages`](https://vcpay.ru/ai/docs/api/inference/messages) | заголовки `x-api-key: ВАШ_КЛЮЧ` и `anthropic-version: 2023-06-01` |

## Python, пакет `openai`

```python
from openai import OpenAI

client = OpenAI(api_key="ВАШ_КЛЮЧ", base_url="https://llm.vcpay.ru/v1")
response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Привет"}],
)
```

## Node.js, пакет `openai`

```js
import OpenAI from 'openai'

const client = new OpenAI({ apiKey: 'ВАШ_КЛЮЧ', baseURL: 'https://llm.vcpay.ru/v1' })
const response = await client.chat.completions.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: 'Привет' }],
})
```

## Python, пакет `anthropic`

```python
from anthropic import Anthropic

client = Anthropic(api_key="ВАШ_КЛЮЧ", base_url="https://llm.vcpay.ru")
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Привет"}],
)
```

> У пакета `anthropic` в `base_url` указывается **адрес без** `/v1` — путь `/v1/messages` пакет добавляет сам. У пакета `openai` — наоборот, адрес **с** `/v1`.


## Claude Code

Claude Code ходит в Anthropic API, поэтому переключается переменными окружения:

```bash
export ANTHROPIC_BASE_URL=https://llm.vcpay.ru
export ANTHROPIC_AUTH_TOKEN=ВАШ_КЛЮЧ
claude
```

## Cursor и другие редакторы

Редакторы, умеющие «OpenAI-compatible endpoint», настраиваются одинаково: в настройках модели указывается адрес `https://llm.vcpay.ru/v1`, ключ — ваш, имя модели — из [списка](https://vcpay.ru/ai/docs/api/models).

## Потоковый ответ

Работает в обоих форматах: добавьте `"stream": true` в тело запроса. Ответ приходит событиями SSE по мере генерации.

---

--- [Document source](https://vcpay.ru/ai/docs/guides/billing.md) ---


# Оплата и детализация

## Предоплата

Работа идёт с авансового счёта компании — того же, с которого оплачиваются остальные услуги VCPay. Постоплаты нет: когда средства заканчиваются, запросы перестают проходить, а не уходят в долг.

Счёт выставляется и оплачивается в разделе компании личного кабинета. Закрывающие документы приходят тем же порядком, что по другим услугам.

## Как считается расход

Стоимость запроса складывается из токенов на входе и на выходе. Расход относится к тому ключу, которым сделан запрос, — поэтому ключи и стоит заводить по одному на сервис. Списание считается в долларах на стороне шлюза и переводится в рубли один раз — курс фиксируется, когда запрос тарифицируется, в ближайшие минуты после него. Этот курс сохраняется в строке детализации, так что «курс × расход» в кабинете сходится без остатка.

Три вещи, из-за которых счёт бывает больше, чем кажется по длине ответа:

- **Кешированный вход** тарифицируется отдельно и дешевле обычного — это чтение кэша. **Запись** в кэш — отдельная операция со своей ставкой: запрос, который кэш создаёт, и запрос, который его читает, стоят по-разному, хотя оба «с кэшем». У Claude вендор различает кэш на 5 минут и на час; мы тарифицируем по той ставке, которая настроена на модели, и она одна — её и показывает каталог.
- **Размышления модели (reasoning)** отдельной ставки не имеют — они считаются как выход. У Claude Opus размышления включены по умолчанию, поэтому исходящих токенов на запрос будет заметно больше, чем видно по тексту ответа. Это не ошибка счёта.
- **Округление — только для показа.** Внутри расход считается с точностью до доли копейки и накапливается; в журнал списывается агрегированно, поэтому отдельная строка запроса в кабинете и сумма проводки округляются по-разному.

## Посчитайте счёт сами

Ставки берутся из каталога — он открыт без ключа:

```bash
curl https://llm.vcpay.ru/v1/vcpay/models
```

По каждой модели приходят четыре ставки за миллион токенов: обычный вход, кешированный вход, выход и запись в кэш. Дальше арифметика прямая: каждый вид токенов умножается на свою ставку и делится на миллион.

```text
стоимость = (обычный_вход      × ставка_входа
           + кешированный_вход × ставка_кеш-чтения
           + запись_в_кэш      × ставка_кеш-записи
           + выход             × ставка_выхода) / 1 000 000
```

Токены каждого вида приходят в ответе модели, в поле `usage`. Две подсказки, без которых расчёт не сойдётся:

- **в `completion_tokens` входят размышления.** У Claude Opus они включены по умолчанию, и выход окажется заметно больше видимого текста;
- **чтение и запись кэша — разные ставки.** Запрос, который кэш создаёт, дороже того, который его читает, хотя оба «с кэшем».

Свой остаток и расход по ключу можно спросить у API тем же ключом, которым вы зовёте модели:

```bash
curl https://llm.vcpay.ru/v1/vcpay/balance -H "Authorization: Bearer ВАШ_КЛЮЧ"
curl https://llm.vcpay.ru/v1/vcpay/stats   -H "Authorization: Bearer ВАШ_КЛЮЧ"
```

Как считаются эти цифры и что значит каждое поле — в справочнике: [остаток и потолок ключа](https://vcpay.ru/ai/docs/api/key/balance), [расход ключа](https://vcpay.ru/ai/docs/api/key/stats).

## Как двигается цена

Цена получается из биржевого курса USDT одним умножением:

```text
цена за доллар потребления = биржевой курс USDT × множитель
```

**Множитель публикуется.** Его текущее значение приходит в каталоге полем `sell_rate_multiplier` вместе с версией тарифа, по которой он посчитан. В множитель заложены обмен валюты, комиссии приёма платежа, резерв на колебания и наша маржа — раскладку по каждой составляющей мы не публикуем, но само число вы видите и можете проверить по нему любой свой счёт.

Ход курса идёт насквозь и заранее не объявляется — это часть механизма. **Об изменении множителя предупреждаем не менее чем за 14 дней.** Купленные рубли остаются рублями: сколько токенов на них придётся, зависит от действующего курса.

### Какая цена применится к моему запросу

Две разные величины и два разных момента, и путать их дороже всего:

- **версия тарифа** — та, что действовала **в момент вашего запроса**. Новая версия применяется только к запросам после даты её вступления в силу; задним числом ничего не переоценивается;
- **курс** — тот, что действовал **в момент тарификации**: запрос получает рублёвую цену в ближайшие минуты после ответа модели, и курс запоминается в его строке. Списание на счёт идёт позже и сразу за несколько запросов, но переоценить их оно уже не может.

Ставки за миллион токенов по каждой модели отдаёт каталог API, и он же источник для витрины и для кабинета — поэтому разойтись они не могут. В самом кабинете, в разделе AI API, видно уже посчитанный по этим ставкам расход.

## Что видно в кабинете

- сводка за период: запросов, входящих и исходящих токенов;
- разрез по ключам и по моделям;
- последние запросы с временем и моделью;
- выгрузка построчно в CSV — по ней сверяют наш отчёт со своими логами.

## Чего в детализации нет

Тел запросов и ответов. Мы их не храним — ни в журнале, ни в отчёте, ни в выгрузке. Подробнее — [Границы продукта](https://vcpay.ru/ai/docs/guides/scope).

---

--- [Document source](https://vcpay.ru/ai/docs/guides/scope.md) ---


# Границы продукта

Короткая страница про то, что обычно выясняется в переписке. Лучше знать заранее.

## Содержимое запросов мы не храним

В журнале есть время, модель, ключ и количество токенов. Тел запросов и ответов там нет — ни поля под них, ни места. Это не настройка, которую можно включить: хранить негде.

## Предоплата, без долга

Средства списываются с авансового счёта компании. Кончились — запросы перестают проходить. Постоплаты и кредитного лимита нет.

## Ключ показывается один раз

Мы не храним значение ключа: оно живёт в шлюзе и выдаётся нам один раз при выпуске. Потерянный ключ не восстанавливается — выпускается новый.

## Расход виден с задержкой

Строка расхода создаётся в момент завершения запроса, а в кабинет попадает следующим проходом сборщика — это несколько минут. Для потокового ответа отсчёт идёт от конца потока, а не от начала.

## Удаление ключа не стирает историю

Ключ удаляется насовсем, но расход, который он успел сделать, остаётся в детализации: он уже случился, и по нему выставлен счёт.

## Совместимость — не гарантия одинакового поведения

Мы принимаем запросы в форматах OpenAI и Anthropic и отдаём ответы в них же. Это не значит, что модель поведёт себя как у другого поставщика: набор полей, ограничения и умолчания у моделей свои.

---

--- [Document source](https://vcpay.ru/ai/docs/api/overview.md) ---


# Обзор

Один адрес и один ключ на Claude, Gemini и GPT. Запросы к моделям — в форматах OpenAI и Anthropic, остаток, расход и цены — методами /v1/vcpay тем же ключом.

Если только начинаете, откройте [быстрый старт](https://vcpay.ru/ai/docs/guides/quick-start): ключ, адрес и первый запрос за три шага. Код менять не нужно — работают штатные пакеты [OpenAI и Anthropic](https://vcpay.ru/ai/docs/guides/compatibility).

Базовый URL: `https://llm.vcpay.ru`

Клиенты и SDK:

**Python, openai** — [документация](https://vcpay.ru/ai/docs/guides/compatibility)

```bash
pip install openai
```

**Node.js, openai** — [документация](https://vcpay.ru/ai/docs/guides/compatibility)

```bash
npm install openai
```

**Python, anthropic** — [документация](https://vcpay.ru/ai/docs/guides/compatibility)

```bash
pip install anthropic
```

**Claude Code** — [документация](https://vcpay.ru/ai/docs/guides/compatibility)

```bash
export ANTHROPIC_BASE_URL=https://llm.vcpay.ru
export ANTHROPIC_AUTH_TOKEN=ВАШ_КЛЮЧ
```

Ресурсы:

- [OpenAPI](https://vcpay.ru/ai/docs/openapi.yaml)
- [Postman](https://vcpay.ru/ai/docs/vcpay-ai.postman_collection.json)


## Методы

Все методы и поля их ответов — в справочнике слева. Чаще всего нужны эти.

- [Ответ модели, формат OpenAI](https://vcpay.ru/ai/docs/api/inference/chat-completions)

- [Ответ модели, формат Anthropic](https://vcpay.ru/ai/docs/api/inference/messages)

- [Каталог моделей с ценами](https://vcpay.ru/ai/docs/api/catalog/models)

- [Остаток и потолок ключа](https://vcpay.ru/ai/docs/api/key/balance)

- [Как устроен ключ](https://vcpay.ru/ai/docs/api/key/info)

- [Расход ключа](https://vcpay.ru/ai/docs/api/key/stats)


## Основы API

- [Модели](https://vcpay.ru/ai/docs/api/models) — Имена для вызова и живые цены
- [Ошибки](https://vcpay.ru/ai/docs/api/errors) — Коды отказов и что с ними делать
- [Совместимость](https://vcpay.ru/ai/docs/guides/compatibility) — OpenAI SDK, Anthropic SDK, Claude Code


---

--- [Document source](https://vcpay.ru/ai/docs/api/errors.md) ---


# Ошибки

Ошибка приходит обычным для OpenAI API телом: объект `error` с полем `message`. Ниже — отказы, которые вы реально встретите, и что делать с каждым.

| Код | Сообщение | Что произошло | Что делать |
|---|---|---|---|
| `401` | `Invalid token` | ключ неизвестен, отключён или удалён — или ключу нечего тратить: исчерпан его потолок либо кончились деньги на счёте компании | проверьте, что подставлен целиком; в кабинете — состояние ключа, его потолок и остаток счёта |
| `403` | `token quota is not enough …` | остаток ключа есть, но этот запрос в него не помещается | поднимите потолок ключа или пополните счёт; более короткий запрос может пройти |
| `403` | `This token has no access to model …` | у ключа ограничен список моделей | вызовите разрешённую модель или снимите ограничение в кабинете |
| `503` | `No available channel for model …` | такой модели у нас нет | сверьтесь со [списком моделей](https://vcpay.ru/ai/docs/api/models) — вероятна опечатка в имени |
| `429` | — | слишком много запросов | повторите с задержкой и увеличивайте её при повторных отказах |

> Отключённый, удалённый и исчерпанный ключ отвечают тем же `401`, что и неизвестный: шлюз отсекает ключ с нулевым остатком ещё на проверке ключа. По ответу API нельзя отличить «ключ отозвали» от «ключу нечего тратить» и от «такого ключа не существует» — иначе чужие ключи можно было бы перебирать. Что именно случилось с вашим ключом, видно в кабинете.


## Что повторять, а что нет

Повторять имеет смысл `429` и `5xx` — это временные состояния. `401` и `403` повторять бесполезно: пока вы не измените ключ или его настройки, ответ не изменится.

> **Внимание:** Формат ошибок мы планируем сделать своим — со стабильными кодами, по которым удобно ветвиться, и с явным правилом повтора. Пока этого нет, **не завязывайтесь на текст сообщения**: он приходит от шлюза и может измениться. Ветвитесь по HTTP-коду.


## Если запрос завершился ошибкой, деньги списались?

Нет. В детализацию попадают только завершённые запросы. Отказ до обращения к модели расхода не создаёт.

---

--- [Document source](https://vcpay.ru/ai/docs/api/models.md) ---


# Модели

Модель выбирается полем `model` в запросе. Таблица ниже — живой каталог: она запрашивается у API при открытии страницы, поэтому имена и ставки в ней те же, что сейчас применяет шлюз.

Ставки по моделям в рублях за 1 млн токенов отдаёт каталог без ключа: `GET https://llm.vcpay.ru/v1/vcpay/models` — [справочник](https://vcpay.ru/ai/docs/api/catalog/models).

Ставки — в рублях за миллион токенов. «Кэш: чтение» — вход, прочитанный из кэша, «Кэш: запись» — вход, который кэш создаёт. Прочерк — этот вид тарификации у модели не применяется.

## Актуальный список — у самого API

Каталог пополняется, и источник истины один: сам шлюз. Список моделей, доступных вашему ключу, отдаёт совместимый с OpenAI путь:

```bash
curl https://llm.vcpay.ru/v1/models \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"
```

Тот же список виден в кабинете, в карточке «Подключение» раздела AI API.

> В ответе модель может называться полным именем вендора — например, `anthropic/claude-haiku-4.5` вместо `claude-haiku-4.5`. Оба имени принимаются на входе и означают одну и ту же модель.


## Цены

Ставки за миллион токенов отдаёт сам API — **без ключа**, чтобы их можно было посмотреть до подключения. Таблица выше берёт их оттуда же:

```bash
curl https://llm.vcpay.ru/v1/vcpay/models
```

По каждой модели приходят раздельные ставки в рублях: обычный вход, кешированный вход, выход и запись в кэш. Там же — версия действующего тарифа и множитель к биржевому курсу, из которого цена получена. Все поля ответа — в справочнике: [каталог моделей](https://vcpay.ru/ai/docs/api/catalog/models).

В тексте документации цен нет намеренно: они меняются вслед за курсом, и вписанная сюда цифра устарела бы к моменту, когда вы её прочитали. Как из этих ставок получается счёт — [Оплата и детализация](https://vcpay.ru/ai/docs/guides/billing).

---

# API Методы

## API: Inference

--- [Document source](https://vcpay.ru/ai/docs/api/inference/chat-completions.md) ---

# Ответ модели в формате OpenAI

**Метод**: `POST`

**Путь**: `/v1/chat/completions`

Совместим с OpenAI Chat Completions: штатный пакет `openai` работает, если указать `base_url="https://llm.vcpay.ru/v1"`. Модель выбирается полем `model` — именем из каталога.

С `"stream": true` ответ приходит событиями SSE по мере генерации, последним событием — `data: [DONE]`.

Здесь перечислены поля, работу которых мы проверяем. Остальные поля формата OpenAI модель может принять, но их поведение зависит от модели и не входит в наш контракт.

## Тело запроса

**Обязательно**

Формат: `application/json`

### Схема

- `model: string` (required) — Имя модели из каталога, например `claude-sonnet-5`. Пример: `"claude-sonnet-5"`
- `messages: array of object` (required) — Диалог по порядку, от первой реплики к последней.
  - `role: string` (required) — Кто говорит. `system` — инструкция модели.
    Значения: `system`, `user`, `assistant`
  - `content: string` (required) — Текст реплики.
- `max_tokens: integer` (min: 1) — Потолок токенов ответа. Размышления модели входят в него.
- `stream: boolean` (default: false) — Отдавать ответ событиями SSE по мере генерации.

### Пример

```json
{
  "model": "claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Привет! Ответь одним словом."
    }
  ]
}
```

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

```bash
curl "https://llm.vcpay.ru/v1/chat/completions" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Привет! Ответь одним словом."
    }
  ]
}'
```

## Ответы

### 200: Ответ модели. При `"stream": true` — поток событий `text/event-stream`, каждое событие — фрагмент ответа.

**Схема ответа:**

- `id: string` (required) — Идентификатор ответа.
- `object: string` (required) — Всегда `chat.completion`.
- `created: integer` (required) — Момент ответа, Unix-время в секундах.
- `model: string` (required) — Модель, которая ответила. Может прийти полным именем вендора, например `anthropic/claude-haiku-4.5`.
- `choices: array of object` (required) — Варианты ответа. Без особых настроек — один.
  - `index: integer` (required) — Номер варианта.
  - `message: object` (required) — Реплика модели.
    - `role: string` (required) — Всегда `assistant`.
    - `content: string` (required) — Текст ответа.
  - `finish_reason: string` (required) — Почему ответ закончился. `stop` — модель договорила, `length` — упёрлись в `max_tokens`.
- `usage: object` (required) — Токены запроса. По ним считается расход.
  - `prompt_tokens: integer` (required) — Токенов на входе.
  - `completion_tokens: integer` (required) — Токенов на выходе, включая размышления модели. У моделей с размышлениями их заметно больше, чем видно по тексту ответа.
  - `total_tokens: integer` (required) — Сумма входа и выхода.

**Пример ответа:**

```json
{
  "id": "gen-1760261400-abc123",
  "object": "chat.completion",
  "created": 1760261400,
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Привет!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}
```

### 401: Ключ неизвестен, отключён или удалён — или ключу нечего тратить: исчерпан его потолок либо кончились деньги на счёте компании.

**Схема ответа при ошибке:**

- `error: object` (required) — Что случилось.
  - `message: string` (required) — Текст отказа для человека. В конце — номер запроса в скобках, его стоит приложить к обращению в поддержку.
  - `type: string` — Класс отказа.
  - `code: string` — Код отказа. Сейчас чаще пустой — ветвитесь по HTTP-коду.

**Пример ответа:**

```json
{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202610120924426549346618268d9d6u9fxTwQg)",
    "type": "new_api_error"
  }
}
```

### 403: Запрос не помещается в остаток ключа, или ключу не разрешена эта модель.

**Схема ответа при ошибке:**

- `error: object` (required) — Что случилось.
  - `message: string` (required) — Текст отказа для человека. В конце — номер запроса в скобках, его стоит приложить к обращению в поддержку.
  - `type: string` — Класс отказа.
  - `code: string` — Код отказа. Сейчас чаще пустой — ветвитесь по HTTP-коду.

**Пример ответа:**

```json
{
  "error": {
    "code": "",
    "message": "This token has no access to model claude-opus-5",
    "type": "new_api_error"
  }
}
```

### 429: Слишком много запросов. Повторите с задержкой и увеличивайте её при повторных отказах.

### 503: Такой модели нет — вероятна опечатка в имени. Сверьтесь с каталогом.

**Схема ответа при ошибке:**

- `error: object` (required) — Что случилось.
  - `message: string` (required) — Текст отказа для человека. В конце — номер запроса в скобках, его стоит приложить к обращению в поддержку.
  - `type: string` — Класс отказа.
  - `code: string` — Код отказа. Сейчас чаще пустой — ветвитесь по HTTP-коду.

**Пример ответа:**

```json
{
  "error": {
    "code": "",
    "message": "No available channel for model claude-sonet-5",
    "type": "new_api_error"
  }
}
```


## SDK примеры

### TypeScript

```typescript
import OpenAI from 'openai';

const client = new OpenAI({ apiKey: 'ВАШ_КЛЮЧ', baseURL: 'https://llm.vcpay.ru/v1' });

const response = await client.chat.completions.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: 'Привет! Ответь одним словом.' }],
});
console.log(response.choices[0].message.content);
```

### Python

```python
from openai import OpenAI

client = OpenAI(api_key="ВАШ_КЛЮЧ", base_url="https://llm.vcpay.ru/v1")

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Привет! Ответь одним словом."}],
)
print(response.choices[0].message.content)
```

---

--- [Document source](https://vcpay.ru/ai/docs/api/inference/messages.md) ---

# Ответ модели в формате Anthropic

**Метод**: `POST`

**Путь**: `/v1/messages`

Совместим с Anthropic Messages API: штатный пакет `anthropic` работает, если указать `base_url="https://llm.vcpay.ru"` — **без** `/v1`, путь `/v1/messages` пакет добавляет сам. Claude Code подключается переменными `ANTHROPIC_BASE_URL=https://llm.vcpay.ru` и `ANTHROPIC_AUTH_TOKEN`.

С `"stream": true` ответ приходит событиями SSE.

Здесь перечислены поля, работу которых мы проверяем. Остальные поля формата Anthropic модель может принять, но их поведение не входит в наш контракт.

## Параметры

### Header параметры

- `anthropic-version: string` (required) — Версия формата Anthropic. Пакет `anthropic` ставит её сам.


## Тело запроса

**Обязательно**

Формат: `application/json`

### Схема

- `model: string` (required) — Имя модели из каталога, например `claude-sonnet-5`. Пример: `"claude-sonnet-5"`
- `max_tokens: integer` (required, min: 1) — Потолок токенов ответа. В формате Anthropic обязателен.
- `system: string` — Инструкция модели.
- `messages: array of object` (required) — Диалог по порядку, от первой реплики к последней.
  - `role: string` (required) — Кто говорит.
    Значения: `user`, `assistant`
  - `content: string` (required) — Текст реплики.
- `stream: boolean` (default: false) — Отдавать ответ событиями SSE.

### Пример

```json
{
  "model": "claude-sonnet-5",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Привет"
    }
  ]
}
```

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

```bash
curl "https://llm.vcpay.ru/v1/messages" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-sonnet-5",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Привет"
    }
  ]
}'
```

## Ответы

### 200: Ответ модели. При `"stream": true` — поток событий `text/event-stream`.

**Схема ответа:**

- `id: string` (required) — Идентификатор ответа.
- `type: string` (required) — Всегда `message`.
- `role: string` (required) — Всегда `assistant`.
- `model: string` (required) — Модель, которая ответила.
- `content: array of object` (required) — Части ответа.
  - `type: string` (required) — Вид части. Текст — `text`.
  - `text: string` (required) — Текст ответа.
- `stop_reason: string` (required) — Почему ответ закончился. `end_turn` — модель договорила, `max_tokens` — упёрлись в потолок.
- `usage: object` (required) — Токены запроса. По ним считается расход.
  - `input_tokens: integer` (required) — Токенов на входе.
  - `output_tokens: integer` (required) — Токенов на выходе, включая размышления модели.

**Пример ответа:**

```json
{
  "id": "msg_01ABCDEF",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {
      "type": "text",
      "text": "Привет! Чем помочь?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 9,
    "output_tokens": 8
  }
}
```

### 401: Ключ неизвестен, отключён или удалён — или ключу нечего тратить: исчерпан его потолок либо кончились деньги на счёте компании. Тело отказа — в формате OpenAI, как у `/v1/chat/completions`.

**Схема ответа при ошибке:**

- `error: object` (required) — Что случилось.
  - `message: string` (required) — Текст отказа для человека. В конце — номер запроса в скобках, его стоит приложить к обращению в поддержку.
  - `type: string` — Класс отказа.
  - `code: string` — Код отказа. Сейчас чаще пустой — ветвитесь по HTTP-коду.

**Пример ответа:**

```json
{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202610120924428084477238268d9d650vH0Yey)",
    "type": "new_api_error"
  }
}
```

### 403: Запрос не помещается в остаток ключа, или ключу не разрешена эта модель.

**Схема ответа при ошибке:**

- `error: object` (required) — Что случилось.
  - `message: string` (required) — Текст отказа для человека. В конце — номер запроса в скобках, его стоит приложить к обращению в поддержку.
  - `type: string` — Класс отказа.
  - `code: string` — Код отказа. Сейчас чаще пустой — ветвитесь по HTTP-коду.

**Пример ответа:**

```json
{
  "error": {
    "message": "Пример текста",
    "type": "string",
    "code": "string"
  }
}
```

### 429: Слишком много запросов. Повторите с задержкой и увеличивайте её при повторных отказах.

### 503: Такой модели нет — вероятна опечатка в имени. Сверьтесь с каталогом.

**Схема ответа при ошибке:**

- `error: object` (required) — Что случилось.
  - `message: string` (required) — Текст отказа для человека. В конце — номер запроса в скобках, его стоит приложить к обращению в поддержку.
  - `type: string` — Класс отказа.
  - `code: string` — Код отказа. Сейчас чаще пустой — ветвитесь по HTTP-коду.

**Пример ответа:**

```json
{
  "error": {
    "message": "Пример текста",
    "type": "string",
    "code": "string"
  }
}
```


## SDK примеры

### TypeScript

```typescript
import Anthropic from '@anthropic-ai/sdk';

// Адрес без /v1: путь /v1/messages пакет добавляет сам.
const client = new Anthropic({ apiKey: 'ВАШ_КЛЮЧ', baseURL: 'https://llm.vcpay.ru' });

const message = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 256,
  messages: [{ role: 'user', content: 'Привет' }],
});
console.log(message.content[0].text);
```

### Python

```python
from anthropic import Anthropic

# Адрес без /v1: путь /v1/messages пакет добавляет сам.
client = Anthropic(api_key="ВАШ_КЛЮЧ", base_url="https://llm.vcpay.ru")

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Привет"}],
)
print(message.content[0].text)
```

---

## API: Catalog

--- [Document source](https://vcpay.ru/ai/docs/api/catalog/models.md) ---

# Каталог моделей с ценами ₽ за 1 млн токенов

**Метод**: `GET`

**Путь**: `/v1/vcpay/models`

> Авторизация не требуется

Модели, которые можно вызвать, и их ставки в рублях за 1 млн токенов: обычный вход, вход из кэша, выход и запись в кэш. **Ключ не нужен** — цены можно посмотреть до подключения.

Цена получается из биржевого курса USDT умножением на `sell_rate_multiplier` и меняется вслед за курсом, поэтому ответ кешируется не дольше 5 минут. Если курс сейчас недоступен, приходит `priced: false` без ставок — повторите запрос позже.

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

```bash
curl "https://llm.vcpay.ru/v1/vcpay/models"
```

## Ответы

### 200: Каталог моделей и ставки

**Схема ответа:**

- `base_url: string` (required) — Адрес, совместимый с OpenAI API
- `priced: boolean` (required) — Цены актуальны. `false` — курс сейчас недоступен, ставки не выданы; повторите позже
- `price_version: object` — Действующая версия тарифа
  - `id: integer` (required) — Номер версии тарифа
  - `effective_from: date-time` (nullable) — С какого момента действует версия, UTC
- `sell_rate_multiplier: string, decimal` (nullable) — Множитель к биржевому курсу USDT, из которого получена цена
- `models: array of object` — Модели и их ставки. Пустой — каталог сейчас недоступен
  - `id: string` (required) — Имя, которым модель вызывают в поле `model`
  - `family: string` (required) — Семейство: Claude, Gemini, GPT
  - `input_rub_mtok: string, decimal` (nullable) — Обычный вход, ₽ за 1 млн токенов
  - `cached_input_rub_mtok: string, decimal` (nullable) — Вход, прочитанный из кэша, ₽ за 1 млн токенов
  - `output_rub_mtok: string, decimal` (nullable) — Выход, включая размышления модели, ₽ за 1 млн токенов
  - `cache_write_rub_mtok: string, decimal` (nullable) — Запись в кэш, ₽ за 1 млн токенов

**Пример ответа:**

```json
{
  "base_url": "https://llm.vcpay.ru/v1",
  "priced": true,
  "price_version": {
    "id": 1,
    "effective_from": "2026-09-18T08:36:43Z"
  },
  "sell_rate_multiplier": "2.00000",
  "models": [
    {
      "id": "claude-sonnet-5",
      "family": "Claude",
      "input_rub_mtok": "100.00",
      "cached_input_rub_mtok": "10.00",
      "output_rub_mtok": "500.00",
      "cache_write_rub_mtok": "125.00"
    }
  ]
}
```

### 429: Слишком много запросов: не больше 10 в секунду с одного адреса. Повторите после паузы


## SDK примеры

### TypeScript

```typescript
const response = await fetch('https://llm.vcpay.ru/v1/vcpay/models');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

### Python

```python
import httpx

response = httpx.get("https://llm.vcpay.ru/v1/vcpay/models")
response.raise_for_status()
print(response.json())
```

---

## API: Key

--- [Document source](https://vcpay.ru/ai/docs/api/key/balance.md) ---

# Остаток счёта и потолок этого ключа

**Метод**: `GET`

**Путь**: `/v1/vcpay/balance`

Сколько денег на лицевом счёте компании и сколько из них может потратить ключ, которым сделан запрос. Авторизация — тем же ключом, которым вызывают модели.

Цифры считаются так же, как потолок, по которому шлюз пропускает запросы:

- `available_rub` = остаток счёта − расход, ещё не списанный со счёта (не меньше нуля);
- `key_budget_rub` = меньшее из `available_rub` и потолка ключа `key_limit_rub`.

Когда `key_budget_rub` равен нулю, запросы к моделям отклоняются.

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

```bash
curl "https://llm.vcpay.ru/v1/vcpay/balance" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"
```

## Ответы

### 200: Остаток счёта и бюджет ключа

**Схема ответа:**

- `account_balance_rub: string, decimal` (required) — Остаток лицевого счёта компании, ₽
- `available_rub: string, decimal` (required) — Сколько можно потратить сейчас: остаток счёта минус расход, ещё не списанный со счёта, ₽. Не бывает меньше нуля
- `debt_rub: string, decimal` (default: 0) — Потрачено сверх остатка и ждёт списания, ₽. Ноль — расход уложился в счёт; больше нуля — следующее пополнение сначала закроет эту сумму
- `key_budget_rub: string, decimal` (required) — Сколько может потратить этот ключ: меньшее из доступного и потолка ключа, ₽
- `key_limit_rub: string, decimal` (nullable) — Свой потолок ключа, ₽. `null` — ключ ограничен только счётом
- `as_of: date-time` (required) — Момент расчёта, UTC

**Пример ответа:**

```json
{
  "account_balance_rub": "48250.00",
  "available_rub": "47312.40",
  "debt_rub": "0",
  "key_budget_rub": "10000.00",
  "key_limit_rub": "10000.00",
  "as_of": "2026-10-12T09:30:00Z"
}
```

### 401: Ключ не передан или не распознан. Отозванный, удалённый и несуществующий ключ отвечают одинаково — что с ключом, видно в кабинете

**Схема ответа при ошибке:**

- `detail: string` (required) — Что случилось, по-русски

**Пример ответа:**

```json
{
  "detail": "Ключ не распознан. Если он выпущен давно, перевыпустите его в кабинете"
}
```

### 409: Ключ распознан, но к нему не подключён лицевой счёт

**Схема ответа при ошибке:**

- `detail: string` (required) — Что случилось, по-русски

**Пример ответа:**

```json
{
  "detail": "по этому ключу лицевой счёт не подключён"
}
```

### 429: Слишком много запросов: не больше 10 в секунду с одного адреса, и не больше 120 в минуту на ключ. Повторите после паузы


## SDK примеры

### TypeScript

```typescript
const response = await fetch('https://llm.vcpay.ru/v1/vcpay/balance', {
  headers: { Authorization: 'Bearer ВАШ_КЛЮЧ' },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

### Python

```python
import httpx

response = httpx.get(
    "https://llm.vcpay.ru/v1/vcpay/balance",
    headers={"Authorization": "Bearer ВАШ_КЛЮЧ"},
)
response.raise_for_status()
print(response.json())
```

---

--- [Document source](https://vcpay.ru/ai/docs/api/key/info.md) ---

# Как устроен этот ключ

**Метод**: `GET`

**Путь**: `/v1/vcpay/key`

Имя, потолок расхода, срок действия и разрешённые модели ключа, которым сделан запрос. Значение ключа API не возвращает — его показывают один раз, при выпуске в кабинете.

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

```bash
curl "https://llm.vcpay.ru/v1/vcpay/key" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"
```

## Ответы

### 200: Настройки ключа

**Схема ответа:**

- `id: integer` (required) — Идентификатор ключа. Значение ключа API не возвращает никогда
- `name: string` (required) — Имя ключа, которое дали при выпуске в кабинете
- `created_at: date-time` (required) — Когда ключ выпущен, UTC
- `limit_rub: string, decimal` (nullable) — Свой потолок расхода, ₽. `null` — ограничен остатком счёта
- `expires_at: date-time` (nullable) — Срок действия, UTC. `null` — бессрочный
- `models: array of string` (nullable) — Разрешённые модели. Пустой список — без ограничения; `null` — узнать не удалось, повторите запрос позже

**Пример ответа:**

```json
{
  "id": 42,
  "name": "backend-prod",
  "created_at": "2026-09-20T11:04:00Z",
  "limit_rub": "10000.00",
  "expires_at": null,
  "models": [
    "claude-sonnet-5",
    "claude-haiku-4.5"
  ]
}
```

### 401: Ключ не передан или не распознан. Отозванный, удалённый и несуществующий ключ отвечают одинаково — что с ключом, видно в кабинете

**Схема ответа при ошибке:**

- `detail: string` (required) — Что случилось, по-русски

**Пример ответа:**

```json
{
  "detail": "Ключ не распознан. Если он выпущен давно, перевыпустите его в кабинете"
}
```

### 429: Слишком много запросов: не больше 10 в секунду с одного адреса, и не больше 60 в минуту на ключ. Повторите после паузы


## SDK примеры

### TypeScript

```typescript
const response = await fetch('https://llm.vcpay.ru/v1/vcpay/key', {
  headers: { Authorization: 'Bearer ВАШ_КЛЮЧ' },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

### Python

```python
import httpx

response = httpx.get(
    "https://llm.vcpay.ru/v1/vcpay/key",
    headers={"Authorization": "Bearer ВАШ_КЛЮЧ"},
)
response.raise_for_status()
print(response.json())
```

---

--- [Document source](https://vcpay.ru/ai/docs/api/key/stats.md) ---

# Расход этого ключа

**Метод**: `GET`

**Путь**: `/v1/vcpay/stats`

Запросы, токены и рубли этого ключа за текущие сутки (с 00:00 UTC) и за последние 30 суток. Другие ключи счёта сюда не входят.

Рубли появляются, когда запрос тарифицирован, — в ближайшие минуты после ответа модели. Пока этого не случилось, `priced` равен `false`.

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

```bash
curl "https://llm.vcpay.ru/v1/vcpay/stats" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"
```

## Ответы

### 200: Расход ключа за сутки и за 30 дней

**Схема ответа:**

- `today: object` (required) — С 00:00 UTC текущих суток
  - `requests: integer` (required) — Завершённых запросов к моделям
  - `prompt_tokens: integer` (required) — Токенов на входе
  - `completion_tokens: integer` (required) — Токенов на выходе, включая размышления модели
  - `cached_tokens: integer` (required) — Токенов входа, прочитанных из кэша
  - `cost_rub: string, decimal` (required) — Тарифицированный расход за окно, ₽
- `last_30d: object` (required) — Последние 30 суток до момента запроса
  - `requests: integer` (required) — Завершённых запросов к моделям
  - `prompt_tokens: integer` (required) — Токенов на входе
  - `completion_tokens: integer` (required) — Токенов на выходе, включая размышления модели
  - `cached_tokens: integer` (required) — Токенов входа, прочитанных из кэша
  - `cost_rub: string, decimal` (required) — Тарифицированный расход за окно, ₽
- `priced: boolean` (required) — Расход уже тарифицирован. `false` — нули в `cost_rub` означают «ещё не посчитано», а не «бесплатно»

**Пример ответа:**

```json
{
  "today": {
    "requests": 214,
    "prompt_tokens": 412300,
    "completion_tokens": 51870,
    "cached_tokens": 120400,
    "cost_rub": "237.61"
  },
  "last_30d": {
    "requests": 5127,
    "prompt_tokens": 9884100,
    "completion_tokens": 1240300,
    "cached_tokens": 3011200,
    "cost_rub": "5604.18"
  },
  "priced": true
}
```

### 401: Ключ не передан или не распознан. Отозванный, удалённый и несуществующий ключ отвечают одинаково — что с ключом, видно в кабинете

**Схема ответа при ошибке:**

- `detail: string` (required) — Что случилось, по-русски

**Пример ответа:**

```json
{
  "detail": "Ключ не распознан. Если он выпущен давно, перевыпустите его в кабинете"
}
```

### 429: Слишком много запросов: не больше 10 в секунду с одного адреса, и не больше 120 в минуту на ключ. Повторите после паузы


## SDK примеры

### TypeScript

```typescript
const response = await fetch('https://llm.vcpay.ru/v1/vcpay/stats', {
  headers: { Authorization: 'Bearer ВАШ_КЛЮЧ' },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

### Python

```python
import httpx

response = httpx.get(
    "https://llm.vcpay.ru/v1/vcpay/stats",
    headers={"Authorization": "Bearer ВАШ_КЛЮЧ"},
)
response.raise_for_status()
print(response.json())
```

---

## Дополнительная информация

- **Веб-сайт**: https://vcpay.ru/
- **Кабинет, выпуск ключа**: https://vcpay.ru/dashboard/company/ai

---

_Документация автоматически сгенерирована из OpenAPI спецификации_