# Souz API

Один API-ключ к моделям текста, изображений, видео, музыки, транскрибации и синтеза речи.
Чат — по контракту OpenAI Chat Completions, остальное — по SDK OpenAI, где у него есть метод.
Баланс в рублях; списывается только успешный запрос, по факту.

- **Адрес:** `https://api.souz.ai`, все методы — под `/v1`.
- **Ключ:** заголовок `Authorization: Bearer <api-key>`. Ключ создаётся в кабинете на
  [souz.ai](https://souz.ai) — [как получить](https://souz.ai/docs/authentication.md).
- **SDK:** любой SDK OpenAI с `base_url = "https://api.souz.ai/v1"` — без пути метода:
  с `…/v1/chat/completions` в `base_url` SDK обращается к несуществующему адресу, и ответ
  `404 not_found` подсказывает верный `base_url`.
- **Каталог моделей:** `GET /v1/models` без ключа — поля запроса, цены и статистика каждой
  модели.

## Как устроен API

- **Чат** отвечает сразу, в том числе потоком (`"stream": true`) — [Чат](https://souz.ai/docs/chat.md).
- **Картинки, музыка, транскрибация и речь** — задача с результатом в том же ответе;
  **видео** — задача с результатом позже: опросом, потоком событий или вебхуком —
  [Задачи и долгие операции](https://souz.ai/docs/jobs.md).
- **Каналы.** У модели один или несколько каналов с разной ценой и скоростью. Канал не
  выбран — его выбирает Авто-роутинг по пресету и при отказе берёт следующий —
  [Авто-роутинг и пресеты](https://souz.ai/docs/routing.md), [Каналы](https://souz.ai/docs/channels.md).
- **Деньги** — целые микроединицы (`1 000 000` = 1 ₽) рядом с полем `currency`; итог
  есть в каждом ответе — [Цены и баланс](https://souz.ai/docs/pricing.md).
- **Ошибки** — один конверт `{"error": {...}}` с кодом и полем запроса, которое нужно
  исправить, — [Ошибки](https://souz.ai/docs/errors.md).

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

Начните с `https://api.souz.ai/llms.txt` — выжимка для агента на одной странице: адрес,
ключ, задачи, ошибки, роутинг и каналы. Markdown любой страницы — адрес плюс `.md`; всё
руководство — `https://souz.ai/llms-full.txt`, оглавление со ссылками на страницы и
модели — `https://souz.ai/llms.txt`; MCP — `https://api.souz.ai/mcp`
([MCP-сервер](https://souz.ai/docs/mcp.md), [Для ИИ-агентов](https://souz.ai/docs/agents.md)).

---

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