# Для ИИ-агентов

Агенту, который пишет код под Souz API, сначала нужна выжимка `https://api.souz.ai/llms.txt`:
адрес, ключ, задачи, ошибки, роутинг и каналы на одной странице. Поля запроса — из карточки
модели, подробности — на страницах руководства.

## Где документация для агента

| Что | Адрес |
|---|---|
| коротко для агента — начать отсюда | `https://api.souz.ai/llms.txt` |
| оглавление сайта со ссылками на Markdown-страницы | `https://souz.ai/llms.txt` |
| всё руководство одним файлом | `https://souz.ai/llms-full.txt`; с приложенной спецификацией — `https://api.souz.ai/llms-full.txt` |
| любая страница документации в Markdown | адрес страницы плюс `.md`, например `https://souz.ai/docs/quickstart.md` |
| страница модели в Markdown | `https://souz.ai/models/<id>.md` |
| контракт | `https://api.souz.ai/openapi.json`, `https://api.souz.ai/openapi.yaml` |

## Порядок работы

1. `GET /v1/models/{id}` — `input_schema` как `parameters` инструмента.
2. Статистика: `stats_7d` в `GET /v1/models`, по часам — `GET /v1/models/{id}/stats`.
3. Отправьте запрос: синхронно (картинки, музыка, транскрибация, речь) или с
   `Prefer: respond-async` и `callback_url` (видео и долгие модели). Ставьте
   `Idempotency-Key` на каждый запрос, который можете повторить.
4. Скачайте результат в течение суток: ссылки и `file_…` живут 1 день.

Настройки аккаунта сервер применяет сам; поля запроса главнее; `"routing_options": {}` —
без каналов из настроек.

## Как выбрать и закрепить канал

1. `GET /v1/models/{id}/channels` — сравните каналы: ставки (`rates`), задержка
   (`metrics.latency_p50_ms`), скорость чата (`metrics.throughput_p50`), стабильность
   (`history.success_rate`), `limits` и `available`. `null` — мало данных, не ноль.
2. `POST /v1/models/{id}/routing/preview` с параметрами и `routing_options` — порядок
   попыток и цена каждого канала, бесплатно.
3. На один запрос — `"routing_options": {"only": ["blue"]}`. Для всего аккаунта — ключом
   управления: `GET /v1/settings`, добавьте модель в `routing_options` и отправьте карту
   целиком в `PATCH /v1/settings`.
4. Проверьте `channel` в ответе или задаче — это канал, который выполнил запрос.

## Как вести себя при ошибках

Ветвитесь по `error.type`: `invalid_request_error` — правьте запрос по `error.detail[]`;
`rate_limit_error` и `model_error` — ждите `Retry-After` и повторяйте; `billing_error` —
остановитесь и сообщите человеку. `402 key_spend_limit_exceeded` при
`spend_limit_reset: "none"` ждать бесполезно — [Лимиты](https://souz.ai/docs/limits.md).

## Цена или скорость

| Нужно | Поля запроса |
|---|---|
| дешевле, даже если медленнее | `"routing": "cheap"` |
| самый быстрый канал | `"routing": "fast"` |
| не дороже цены пресета в N раз | `"max_price_multiplier": 1.5` — каналы дороже не пробуются |
| ответ не дольше Y секунд | `"routing_options": {"preferred_max_latency_ms": 20000}` — каналы с медианной задержкой (`metrics`, сутки или 7 дней) не больше 20 с первыми, остальные остаются запасными |
| самый быстрый в пределах бюджета | `"routing_options": {"sort": "latency", "max_price": {"request": 3000000}}` — каналы с оценкой запроса дороже 3 ₽ не пробуются, остальные — по задержке |
| свой канал, но с запасными | `"routing_options": {"order": ["red"]}` — сначала красный, затем остальные; `only` и `"allow_fallbacks": false` запасные отключают |

Задержка — `metrics.latency_p50_ms` канала (у чата — до первого токена); канал без замера в
число быстрых не попадает. Следующий канал может стоить дороже: итог может превысить цену
пресета.

## Агенту, который ведёт аккаунт

Выдача ключей субагентам, баланс и расходы — [ключ управления](https://souz.ai/docs/management-key.md).

---

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