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

# Цены и фактические списания

> Получение доступных для API Key цен и подтверждённых списаний из ответов генерации

> [!NOTE]
>
> Для запросов из материкового Китая используйте `https://toapis.cn` как Base URL. Замените `https://toapis.com` на `https://toapis.cn` в примерах ниже.

`GET /v1/pricing` возвращает тарифы на модели изображений и видео, доступные текущему API Key. В ответе уже учтены индивидуальная фиксированная цена или скидка клиента и действующая цена группы.

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

## Авторизация

**Authorization** `string` *required*

API Key для генерации в формате `Bearer YOUR_API_KEY`.

## Параметры запроса

**model** `string`

Точный ID модели. Если параметр не указан, возвращаются все доступные модели изображений и видео.

**type** `string`

Фильтр по `image` или `video`.

**limit** `integer` (default: 100)

Число возвращаемых моделей. Допустимый диапазон: от `1` до `100`.

**after** `string`

Курсор пагинации из поля `next_after` предыдущего ответа.

Региональные варианты Seedance используют отдельные ID моделей. Например, передайте в `model` значение `seedance-2-5`, `seedance-2-5-cn` или `seedance-2-5-global`. Отдельного параметра региона нет.

```bash cURL theme={null}
curl --request GET \
  --url 'https://toapis.com/v1/pricing?model=seedance-2-5' \
  --header 'Authorization: Bearer <token>'
```

```json 200 theme={null}
{
  "object": "list",
  "currency": "USD",
  "data": [
    {
      "id": "seedance-2-5",
      "type": "video",
      "prices": [
        {
          "group": "default",
          "conditions": {"resolution": "720p", "has_video_input": false},
          "charge_type": "per_token",
          "price_basis": "total_tokens",
          "unit": "1m_tokens",
          "unit_price": "4"
        }
      ]
    }
  ],
  "has_more": false,
  "next_after": ""
}
```

Суммы выше показывают только структуру ответа. Используйте значения, которые API вернул для текущего API Key.

## Поля цены

**currency** `string`

Валюта цены. Сейчас это `USD`.

**object** `string`

Тип объекта. Всегда `list`.

**data** `array`

Доступные модели. Каждый элемент содержит точный `id`, `type` и массив `prices`, который может быть пустым.

**has\_more** `boolean`

Указывает, доступна ли следующая страница.

**next\_after** `string`

Курсор для следующего запроса. Пустая строка, если `has_more` равно `false`.

**prices\[].group** `string`

Группа маршрутизации, для которой действует цена. Для API Key с автоматическим выбором группы может вернуться несколько групп.

**prices\[].conditions** `object`

Условия применения цены, включая значения модели по умолчанию, если они влияют на тарификацию. Запрос генерации должен соответствовать этим значениям.

**prices\[].charge\_type** `string`

`per_request`, `per_second` или `per_token`.

**prices\[].price\_basis** `string`

Основа расчёта: `request`, `output_seconds`, `total_tokens` или `text_input_tokens`.

**prices\[].unit** `string`

Единица цены: `request`, `second` или `1m_tokens`.

**prices\[].unit\_price** `string`

Действующая цена за единицу в USD в виде десятичной строки. Индивидуальная цена клиента и коэффициент группы уже учтены; не умножайте цену на коэффициент группы повторно.

Цена также может содержать `input_unit_price`, `input_image_unit_price`, `free_input_image_count`, `minimum_charge_usd` или `image_token_prices`. Для тарифов по времени могут возвращаться `pricing_period`, `pricing_timezone`, `pricing_schedule_version` и `pricing_peak_windows`.

Для тарификации токенов изображений объект `image_token_prices` может содержать `text_input`, `cached_text_input`, `image_input`, `cached_image_input` и `image_output`. Все суммы указаны в USD за 1 миллион токенов.

Каталог возвращает только цены, для которых существует хотя бы один включённый канал-кандидат, совместимый с указанными условиями. Эта проверка не резервирует маршрут и не проверяет текущее состояние канала. Если сервис не может безопасно опубликовать полный тариф, модель может вернуться с пустым массивом `prices`. Пустой массив или отсутствие цены не означает бесплатное использование.

## Поля фактического списания

Если списание можно подтвердить, ответ генерации содержит следующий объект:

```json theme={null}
{
  "billing": {
    "status": "settled",
    "credits": "100",
    "cost_usd": "0.5"
  }
}
```

| Поле | Значение |
| - | - |
| `status` | `pending`, `settled` или `refunded` |
| `credits` | Подтверждённое число списанных ToAPIs Credits в виде десятичной строки |
| `cost_usd` | То же подтверждённое списание в USD в виде десятичной строки |

`pending` означает, что итоговая сумма ещё не определена, поэтому поля суммы отсутствуют. `refunded` означает подтверждённое нулевое итоговое списание. Если весь объект `billing` отсутствует, платформа не смогла подтвердить безопасное публичное значение; это не означает бесплатный запрос.

Объект может находиться в следующих ответах:

* Единый запрос задач изображений и видео `GET /v1/tasks/{task_id}`
* запрос асинхронной задачи изображения `GET /v1/images/generations/{task_id}`
* запрос асинхронной задачи видео `GET /v1/videos/generations/{task_id}`
* `data.billing` в Task Webhook
* верхнеуровневый `billing` в совместимых нестриминговых ответах синхронной генерации или редактирования изображений

Для асинхронных задач используйте запрос статуса после завершения как резервный источник итоговой суммы. Объект может отсутствовать в стриминговых ответах изображений, неподдерживаемых форматах ответа провайдера, запросах Playground и при отложенной пакетной тарификации.

## Поля использования задачи

Запросы задач изображений и видео возвращают подтверждённые оплачиваемые количества в поле `usage` верхнего уровня. Успешные Webhook используют те же определения в `data.usage`. Количества для расчёта платы, токены модели и счётчики инструментов могут возвращаться вместе, если соответствующие данные доступны.

| Поле | Тип | Описание |
| - | - | - |
| `charge_type` | string | Способ тарификации: `per_request`, `per_second` или `per_token` |
| `requests` | integer | Оплачиваемое число запросов. Параметр `n` обычного запроса изображений не умножает это число напрямую; действующий `batch_size` видео Midjourney учитывается |
| `billed_tokens` | integer | Число токенов, использованное для расчёта цены. Некоторые пути обработки изображений используют настроенную базу предварительного списания, которая может отличаться от фактических токенов генерации |
| `output_seconds` | integer | Оплачиваемая длительность выходного видео в целых секундах |
| `input_seconds` | integer | Оплачиваемая длительность входного видео в целых секундах |
| `input_images` | integer | Оплачиваемое число входных изображений после вычета бесплатного лимита |
| `input_tokens`, `output_tokens`, `prompt_tokens`, `completion_tokens`, `total_tokens` | integer | Неотрицательные целые счётчики токенов видеомодели. Возвращаются доступные поля поставщика; подтверждённый расчёт по токенам может дополнить `total_tokens` |
| `tool_usage` | object | Счётчики инструментов, включая доступные `web_search`, `image_search`, `grounding_queries`; возвращаются независимо от данных токенов |

Количество берётся из сохранённых записей оплаты этой задачи. При фиксированной оплате используются количества, подтверждённые при создании, а при отложенном расчёте - итоговые количества. Использование не вычисляется обратно из текущих цен или суммы. `per_request` использует `requests`, `per_second` - `output_seconds`, `per_token` - `billed_tokens`. Дополнительные оплачиваемые входные видео и изображения возвращаются при необходимости и опускаются при нулевом количестве.

Если у старой задачи сохранена только сумма без проверяемых количеств, неподтверждённые поля опускаются. Отсутствующие данные токенов не заменяются нулями. После расчёта по токенам детализация видео сохраняется, только если сообщённый итог совпадает с окончательным оплачиваемым количеством. Доступность `usage` и `billing` независима: отсутствие использования не означает отсутствия списания и не мешает возврату результата. И наоборот, если возвращаются оплачиваемые количества, такие как `charge_type`, то всегда возвращаются и `billing.status=settled` с фактической суммой. Задачи с фиксированной оплатой, списанной целиком при отправке, также возвращают `settled`. Запросы задач и Webhook используют одни и те же условия подтверждения и значения полей.

## Ошибки

| Статус | Код | Значение |
| - | - | - |
| `400` | `invalid_request_error` | Неподдерживаемый параметр запроса или неверный `type` / `limit` |
| `401` / `403` | зависит от причины | API Key неверен, истёк, ограничен или не имеет доступа к аккаунту или группе |
| `404` | `model_not_found` | Точный ID модели недоступен этому API Key |
| `503` | `pricing_unavailable` | Индивидуальные цены нельзя безопасно загрузить; подстановка публичной цены не выполняется |

Ответы используют `Cache-Control: private, no-store`.


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