союз.ai

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

Агенту, который пишет код под 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
страница модели в Markdownhttps://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" ждать бесполезно — Лимиты.

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

НужноПоля запроса
дешевле, даже если медленнее"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 канала (у чата — до первого токена); канал без замера в число быстрых не попадает. Следующий канал может стоить дороже: итог может превысить цену пресета.

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

Выдача ключей субагентам, баланс и расходы — ключ управления.