> ## 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` в примерах ниже.
</Note>

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

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

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

<ParamField header="Authorization" type="string" required>
  API Key для генерации в формате `Bearer YOUR_API_KEY`.
</ParamField>

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

<ParamField query="model" type="string">
  Точный ID модели. Если параметр не указан, возвращаются все доступные модели изображений и видео.
</ParamField>

<ParamField query="type" type="string">
  Фильтр по `image` или `video`.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Число возвращаемых моделей. Допустимый диапазон: от `1` до `100`.
</ParamField>

<ParamField query="after" type="string">
  Курсор пагинации из поля `next_after` предыдущего ответа.
</ParamField>

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

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

<ResponseExample>
  ```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": ""
  }
  ```
</ResponseExample>

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

## Поля цены

<ResponseField name="currency" type="string">
  Валюта цены. Сейчас это `USD`.
</ResponseField>

<ResponseField name="object" type="string">
  Тип объекта. Всегда `list`.
</ResponseField>

<ResponseField name="data" type="array">
  Доступные модели. Каждый элемент содержит точный `id`, `type` и массив `prices`, который может быть пустым.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Указывает, доступна ли следующая страница.
</ResponseField>

<ResponseField name="next_after" type="string">
  Курсор для следующего запроса. Пустая строка, если `has_more` равно `false`.
</ResponseField>

<ResponseField name="prices[].group" type="string">
  Группа маршрутизации, для которой действует цена. Для API Key с автоматическим выбором группы может вернуться несколько групп.
</ResponseField>

<ResponseField name="prices[].conditions" type="object">
  Условия применения цены, включая значения модели по умолчанию, если они влияют на тарификацию. Запрос генерации должен соответствовать этим значениям.
</ResponseField>

<ResponseField name="prices[].charge_type" type="string">
  `per_request`, `per_second` или `per_token`.
</ResponseField>

<ResponseField name="prices[].price_basis" type="string">
  Основа расчёта: `request`, `output_seconds`, `total_tokens` или `text_input_tokens`.
</ResponseField>

<ResponseField name="prices[].unit" type="string">
  Единица цены: `request`, `second` или `1m_tokens`.
</ResponseField>

<ResponseField name="prices[].unit_price" type="string">
  Действующая цена за единицу в USD в виде десятичной строки. Индивидуальная цена клиента и коэффициент группы уже учтены; не умножайте цену на коэффициент группы повторно.
</ResponseField>

Цена также может содержать `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/images/generations/{task_id}`
* запрос асинхронной задачи видео `GET /v1/videos/generations/{task_id}`
* `data.billing` в Task Webhook
* верхнеуровневый `billing` в совместимых нестриминговых ответах синхронной генерации или редактирования изображений

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

## Ошибки

| Статус        | Код                     | Значение                                                                                  |
| ------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
| `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`.