# Модели и каталог

Карточка модели — поля запроса, цены и статистика. Стройте запрос по ней.

## Список и карточка

`GET /v1/models` (фильтр `?modality=chat|image|video|music|transcription|speech`) и
`GET /v1/models/{id}` работают без ключа и совместимы с `models.list` и
`models.retrieve` SDK OpenAI: `created` — unix-время `added_at`, `owned_by` — `vendor.id`.
Карточка — схема `Model`.

```bash
curl https://api.souz.ai/v1/models/nano-banana-pro
```

## Поля запроса: `input_schema`, `params`, `rules`

- `input_schema` — **JSON Schema 2020-12 тела запроса к модели**. Подходит как
  `parameters` инструмента или `inputSchema` MCP. Значения, принимаемые молча (`auto`,
  `n: 1`), в ней есть.
- `params[]` — те же поля для интерфейса: подписи, подсказки, умолчания.
- `rules[]` — сочетания значений, которые JSON Schema не выражает (`when` → `allow` или
  `deny`). Запрос с недопустимым сочетанием — `400 capability_mismatch` с
  `reason: "incompatible_value"` и тем, что подошло бы.
- `limits` — пределы модели, `capabilities` у чата — `tools`, `vision`,
  `structured_output`, `streaming`, `file_input`, `audio_input`, `video_input` и
  `supported_parameters` — параметры запроса, которые учитывает хотя бы один канал модели
  (поля нет, если список опубликован не у всех каналов).

### Численные ограничения схемы

`input_schema` строится из тех же данных, которыми проверяется запрос.
Условные границы представлены `allOf` с `if/then`; Unicode — `minLength` и
`maxLength`, количество — `minItems` и `maxItems`, секунды — `minimum` и
`maximum`. Расширение `x-request-limits` сохраняет точные единицы и условия,
включая UTF-16 и байты, для которых стандартной границы JSON Schema нет.
Граница конкретного канала может быть уже: Авто-роутинг не отправит запрос в такой
канал и выберет подходящий по обычным правилам.

## Длина текста

Предел текстового поля указан в `input_schema` как `maxLength` и в `params[]`
как `max_length`. Длина считается в символах Unicode; кириллица и эмодзи не
считаются по байтам. Превышение предела модели возвращает
`400 capability_mismatch` с указанием поля и допустимой длины до обработки вложений.
Если предел не указан, карточка не задаёт верхнюю границу этого поля; это не
означает, что любой объём текста поддерживается.

У музыки предел может зависеть от действия и режима своего текста. Эти условия
публикуются в `input_schema.allOf` через `if` / `then`; общий `max_length` поля
не заменяет ограничения выбранного режима. У диалога речи общий предел `input`
применяется к сумме реплик с переводом строки между ними, а предел поля
`dialogue[].text` — к каждой реплике.

У отдельных каналов допустимая длина может быть меньше. Авто-роутинг исключает
неподходящие каналы до отправки запроса. Если ни один из выбранных каналов не
принимает параметры, запрос получает `400 capability_mismatch`.
Текст запроса автоматически не обрезается.

У чатов ограничения выражены в токенах. Проверяются известные пределы модели
и выбранных каналов, включая сумму входа и запрошенного выхода на один ответ.
`n` увеличивает общий объём ответа, но не размер одного контекста. Проверка
входа использует предварительную оценку токенов.

## Цены в карточке

`pricing` — цена «от»: у изображений `amount_micro` — наименьшая цена каналов
для параметров по умолчанию, как в `GET /v1/models/{id}/channels`. Цены других
сочетаний находятся в `options`. У чата `input_micro`, `output_micro` и
`cache_read_micro` — ставки одного канала: самого дешёвого по сумме 1M входа и 1M выхода, как
первый канал пресета `cheap`. У остальных модальностей — минимум по каналам и сочетаниям
параметров. Рядом — верх ставки (`max_input_micro`, `max_output_micro`,
`max_cache_read_micro`, `max_amount_micro`; `null` — общего верха в этой единице нет),
цены опций пресетов роутинга (`pricing.presets`, по сочетаниям параметров —
`pricing.options[].presets`) и цена каждого канала (`pricing.channels`,
`pricing.options[].channels`). `dynamic: true` — у части каналов динамическая цена
([Цены и баланс](https://souz.ai/docs/pricing.md#динамическая-цена)). Как считается итог — [Цены и баланс](https://souz.ai/docs/pricing.md).

## Статистика

- `stats_7d` в каталоге — итоги 7 дней по запросам всех клиентов: `requests`, `succeeded`
  и `failed`, доля успешных, медиана и p95 времени ответа, у чата — выданные токены
  (схема `ModelStatsSummary`).
- `GET /v1/models/{id}/stats` (без ключа, схема `ModelStats`) — те же числа по часам (у часа —
  медиана `latency_p50_ms`, полоса `latency_p05_ms`–`latency_p95_ms`, края `latency_min_ms` и
  `latency_max_ms`) и `speed` — скорость каждой опции пресетов роутинга по 6 часов (у чата — токенов в
  секунду, у остальных — секунды выполнения).

`stats_7d` обновляется раз в час, `/stats` — раз в минуту (`updated_at`). Доля успешных — среди завершённых запросов, без
отказов по вине запроса (ошибка во входных данных, нехватка баланса). Собственные
служебные запросы платформы (проверки и замеры) в запросы, долю успешных и время ответа не входят.
Время ответа — по успешным запросам, медиана и p95 округлены до ±10 %.

Каталог моделей, карточка и список каналов с авторизацией возвращают цены текущего
аккаунта. Такие ответы имеют `Cache-Control: private, no-cache`; сохранять их в общем
кэше нельзя. Без авторизации каталог по-прежнему доступен.

## Каналы модели

Цены, задержка, скорость и стабильность каналов — `GET /v1/models/{id}/channels`
([Каналы](https://souz.ai/docs/channels.md)).

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.