> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Тарификация и оплата

> Как считается стоимость, как читать списания и пополнять баланс

Деньги списываются с одного кошелька в рублях. Отдельных аккаунтов и отдельных счетов у провайдеров моделей нет.

## Как считается стоимость

Способ зависит от типа задачи:

| Тип | Как считается | Где смотреть цену |
| - | - | - |
| Текст | За токены | `GET /api/v1/models` |
| Изображения, видео, аудио, музыка | За генерацию | `GET /api/v1/media/models` |

### Текст: за токены

Цены публикуются за **миллион** токенов и разделены на входные и выходные. В каталоге это поля `cost_context` и `cost_completion`, десятичные строки, рядом лежит `currency` — обычно `RUB`.

Цена, которую вы видите в каталоге, — это и есть цена списания. Никакого дополнительного начисления поверх неё нет.

### Медиа: за генерацию

Способ зависит от модели:

| Тип цены | Что означает |
| - | - |
| Фиксированная | Одна цена за задачу |
| По параметрам | Цена выбирается по совпадению параметров: разрешение, качество, соотношение сторон |
| По единице | Цена умножается на объём: на секунду длительности, на знак для синтеза речи, на количество изображений `n` |

<Info>
  Точную цену любой медиа-модели читайте в поле `pricing` ответа `GET /api/v1/media/models`, а не в таблице документации: поле всегда соответствует текущей версии API. Поле `pricing.type` показывает, какой из трёх способов применён. Разбор поля — на странице [Каталог медиа-моделей](/docs/api-reference/media/models).
</Info>

## Когда списываются деньги

Плата за медиа-задачу списывается в момент создания — то есть платите вы за запуск, а не за успешный результат. Задача остаётся оплаченной, пока выполняется.

Если отправка задачи провайдеру не удалась, списание возвращается автоматически.

<Warning>
  Повторная отправка запроса на создание задачи с новым `Idempotency-Key` — это новая задача и новое списание. Переотправляйте запрос с **тем же** ключом: повтор вернёт исходную задачу без повторного списания.
</Warning>

### Посекундная тарификация

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

```bash cURL theme={null} theme={null}
curl -X POST https://speshu.ai/api/v1/media/probe-duration \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.speshu.ai/media/2026/10/track.mp3"}'
```

```json theme={null} theme={null}
{ "code": 200, "msg": "success", "data": { "duration_seconds": 12.34 } }
```

Умножьте `duration_seconds` на цену секунды из `pricing` модели — и вы знаете стоимость до списания.

## Как прочитать списание в ответе

В каждом ответе текстовой модели в `usage.cost` лежит сумма, **списанная с вашего кошелька в рублях**:

```json theme={null} theme={null}
"usage": {
  "prompt_tokens": 9,
  "completion_tokens": 7,
  "total_tokens": 16,
  "cost": { "input_cost": 0.0002, "output_cost": 0.0006, "total_cost": 0.0008 }
}
```

| Поле | Что означает |
| - | - |
| `usage.cost.input_cost` | Списание за входные токены |
| `usage.cost.output_cost` | Списание за выходные токены |
| `usage.cost.total_cost` | Итог: `input_cost` + `output_cost` |

<Warning>
  `total_cost` — это сумма списания, а не себестоимость на стороне провайдера модели. В счёт идут именно ваши деньги, и именно эта сумма должна сойтись с вашим расчётом по каталогу.
</Warning>

Так работают `/api/v1/chat/completions` и `/api/v1/responses`. У `/api/v1/messages` форма ответа повторяет формат Anthropic, и объекта `cost` в нём нет: там считайте расход по формату чата либо по остатку на [эндпоинте баланса](/docs/api-reference/other/balance).

## Пример расчёта

Допустим, модель стоит `150.00` за миллион входных токенов и `600.00` за миллион выходных. Запрос из примера выше вернул `prompt_tokens: 9` и `completion_tokens: 7`.

```python Python theme={null} theme={null}
from decimal import Decimal

MILLION = Decimal(1_000_000)

price_in = Decimal("150.00")
price_out = Decimal("600.00")

prompt_tokens = 9
completion_tokens = 7

cost = (
    price_in * Decimal(prompt_tokens) / MILLION
    + price_out * Decimal(completion_tokens) / MILLION
)

print(cost.quantize(Decimal("0.000001")), "₽")
# 0.005550 ₽
```

Считайте через десятичное число, а не через `float`: суммы приходят строками, и двоичное представление накапливает ошибку, которая проявится при сверке списаний.

## Токены рассуждений и кэша

Две составляющие `usage` считаются не так, как можно ожидать, и это регулярный источник недооценки расходов.

**Токены рассуждений** тарифицируются как выходные. Они видны в `usage.completion_tokens_details.reasoning_tokens` и уже включены в `completion_tokens` — отдельно платить за них не нужно, но увеличение `effort` напрямую увеличивает чек.

**Закэшированные входные токены** видны в `usage.prompt_tokens_details.cached_read_tokens`. Они учитываются по сниженной тарифной ставке там, где это поддерживается.

## Баланс

Остаток доступен без обёртки — объект «валюта → десятичная строка»:

```bash cURL theme={null} theme={null}
curl https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"
```

```json theme={null} theme={null}
{ "RUB": "1250.00", "USD": "3.75" }
```

У аккаунта без записей в кошельке вернётся пустой объект `{}` — это не ошибка.

<Info>
  Суммы приходят строками. Разбирайте их в десятичный тип (`Decimal`, `decimal.Decimal`, `BigDecimal`), а не в `float`.
</Info>

### Проверка перед дорогим запросом

Запрос к платной модели отклоняется с кодом `402 insufficient_quota`, если баланс неположительный. Проверка происходит **до** обращения к провайдеру модели, то есть деньги за отказ не списываются.

Бесплатные и нулевые по цене модели проходят без этой проверки.

### Пополнение

Пополнение баланса — в веб-приложении, на [speshu.ai/profile](https://speshu.ai/profile): банковская карта либо счёт для юридических лиц.

## Тариф и оплата по факту

Тариф может включать месячную квоту запросов и токенов. Пока вы в квоте, запросы в неё попадают.

Что происходит после исчерпания квоты, зависит от эндпоинта. На `/api/v1/chat/completions` запрос может молча уйти на резервную модель и посчитаться по факту. Подробности — на странице [Лимиты](/docs/limits).

## Валюты

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

## Юридическим лицам

Для организаций и ИП доступны выставление счёта и закрывающие документы — см. страницу [Бизнес-кейсы](/docs/enterprise).

## Что дальше

<CardGroup cols={2}>
  <Card title="Каталог моделей" icon="microchip" href="/docs/api-reference/models/list">
    Цены за миллион токенов
  </Card>

  <Card title="Каталог медиа-моделей" icon="boxes-stacked" href="/docs/api-reference/media/models">
    Поле `pricing` и тарифы генерации
  </Card>

  <Card title="Баланс" icon="credit-card" href="/docs/api-reference/other/balance">
    Остаток кошелька по валютам
  </Card>

  <Card title="Лимиты" icon="gauge-high" href="/docs/limits">
    Квоты тарифа и таймауты
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.