# api9.ru — Полное руководство для ИИ-агентов и разработчиков (Router 2.0)

**Базовый URL шлюза:** `https://api9.ru`  
**Базовый URL для OpenAI SDK:** `https://api9.ru/v1`  
**Интерактивный веб-тестер и справочник:** `https://api9.ru/guide`  
**Аутентификация (единая для всех методов):** `Authorization: Bearer <YOUR_API_KEY>`  
**Формат тела запросов:** `Content-Type: application/json` (кроме `POST /v1/audio/transcriptions` — `multipart/form-data`)

`https://api9.ru` — единый высокоскоростной корпоративный ИИ-шлюз (Router 2.0). Один API-ключ открывает генерацию текста, многошаговые рассуждения, код, синтез и распознавание речи, генерацию звуковых сцен и музыки, создание и редактирование изображений, удаление фона, 4K-апскейл, генерацию видео, веб-поиск, скрейпинг, OCR документов, проверку контрагентов ЕГРЮЛ (DaData), векторные эмбеддинги, кросс-энкодерный реранк, векторную базу данных и прямые зеркала 60+ провайдеров.

---

## ЧАСТЬ 1. Алгоритм принятия решений для ИИ-агента (Foolproof Decision Tree)

Этот раздел написан специально для автономных ИИ-агентов (включая легковесные и простые модели). Следуй правилам **ЕСЛИ → ТО** строго сверху вниз без отклонений.

### 1.1. Шпаргалка выбора эндпоинта одной строкой

Выбери **ровно одну** строку, подходящую под твою задачу:

| Условие задачи | Какой метод и путь вызывать | Главные параметры |
|---|---|---|
| Короткий ответ / чат (вход ≤ 6 000 токенов) | `POST /v1/chat/completions` | `model="auto:fast"`, `messages=[...]` |
| Максимальное качество текста / сложная аналитика | `POST /v1/chat/completions` | `model="auto:flagship"`, `messages=[...]` |
| Математика, логика, цепочка рассуждений | `POST /v1/chat/completions` | `model="auto:reasoning"`, `max_tokens=2048` |
| Написание, рефакторинг или отладка кода | `POST /v1/chat/completions` | `model="auto:coding"`, `messages=[...]` |
| Строгий JSON по схеме (JSON Schema) | `POST /v1/chat/completions` | `model="auto:smart"`, `json_schema={...}` (без `temperature`) |
| Большой документ / промпт (> 6 000 токенов) | `POST /v1/chat/completions` | `model="auto:long"`, `messages=[...]` |
| Массовая обработка коротких промптов (до 500 шт.) | `POST /v1/batch` | `requests=[{"endpoint":"/text","body":{...}}]`, `concurrency=16` |
| Написать длинную статью с проверкой фактов в вебе | `POST /article` | `topic="...", words=800, ground=true` |
| Сгенерировать картинку с нуля | `POST /mirror/image/generate` | `prompt="..."` (на английском), `aspect_ratio="1:1"` |
| Изменить готовую картинку по инструкции | `POST /mirror/image/edit` | `image="<URL или base64>"`, `prompt="..."` (JSON, не multipart!) |
| Вырезать фон (получить прозрачный PNG) | `POST /mirror/image/remove-bg` | `image="<URL или base64>"` |
| Увеличить чёткость / разрешение картинки (2x–4K) | `POST /mirror/image/upscale` | `image="<URL или base64>"`, `target_width=2048`, `target_height=2048` |
| Нарисовать векторную SVG-диаграмму / инфографику | `POST /infographic` | `topic="..."`, `data_points=["..."]` |
| Сгенерировать видеоролик (из текста или фото) | `POST /mirror/video/generate` | `prompt="..."`, `wait=120` (или `wait=0` + опрос `GET /v1/video/{job_id}`) |
| Озвучить текст голосом (TTS) | `POST /mirror/audio/tts` | `text="..."`, `voice="onyx"` (муж.) или `"nova"` (жен.) |
| Распознать речь из аудио в текст (STT) | `POST /mirror/audio/stt` | `audio_url="..."` (или `audio_b64`), `language="ru"` |
| Сгенерировать звук / фоновый шум / foley (SFX) | `POST /mirror/audio/sfx` | `prompt="..."` (на английском), `duration_seconds=5.0` |
| Сгенерировать музыкальный трек (MP3) | `POST /mirror/audio/music` | `prompt="..."`, `duration_ms=30000` |
| Найти ссылки в интернете | `POST /search` | `query="..."`, `max_results=5` |
| Найти официальный сайт, реестры и контакты фирмы | `POST /search/company` | `name="..."`, `inn="..."`, `city="..."` |
| Получить готовый ответ на вопрос со ссылками | `POST /answer` | `query="..."`, `scrape_top=3` |
| Скачать веб-страницу как чистый Markdown | `POST /scrape` | `url="https://..."` |
| Распознать PDF или скан документа (с таблицами) | `POST /v1/ocr` | `document_url="https://..."` (или `image_url` / `document_b64`) |
| Извлечь JSON по схеме из текста или PDF/картинки | `POST /extract` | `json_schema={...}`, `text="..."` (или `document_url`) |
| Собрать полное B2B-досье компании (ЕГРЮЛ + веб) | `POST /enrich` | `inn="..."`, `name="..."`, `category="requisites"` (или `"contacts"`) |
| Получить точные реквизиты ЕГРЮЛ/ЕГРИП по ИНН | `POST /dadata/findById/party` | `{"query": "7707083893", "branch_type": "MAIN"}` |
| Стандартизовать адрес / телефон / ФИО | `POST /dadata/clean/address` | `["мск сухонская 11/-89"]` (строго JSON-массив строк!) |
| Получить векторные эмбеддинги текста | `POST /embeddings` | `texts=["..."]`, `provider="cohere"`, `input_type="search_document"` |
| Отсортировать найденные документы по релевантности | `POST /rerank` | `query="..."`, `documents=["..."]`, `top_n=5` |
| Сохранить тексты в векторную БД (авто-эмбеддинг) | `POST /vector/upsert` | `items=[{"id":"1","text":"..."}]`, `namespace="my_ns"`, `dimension=1024` |
| Найти похожие записи в векторной БД по смыслу | `POST /vector/query` | `query="..."`, `namespace="my_ns"`, `dimension=1024`, `top_k=5` |

---

### 1.2. Чек-лист: 12 фатальных ошибок глупых агентов и как их избежать

Перед отправкой любого запроса проверь эти 12 правил:

1. **ОШИБКА 1: Передача `temperature != 1` в `gpt-5.6-sol` через нативное зеркало `/mirror/openai/...`.**
   * *Почему падает:* Модели OpenAI серии `gpt-5.6-sol`, `gpt-5.5` и `o1/o3/o4` отвергают `max_tokens` (требуют `max_completion_tokens`) и отвергают любую `temperature`, кроме `1`.
   * *Как правильно:* Вызывай их через унифицированный роутер `POST /v1/chat/completions` или `POST /mirror/text/chat` — шлюз сам подставит `max_completion_tokens` и уберёт несовместимую температуру.

2. **ОШИБКА 2: Смешивание разных размерностей векторов (`512`, `1024`, `1536`, `2048`) в одном векторном индексе.**
   * *Почему падает:* Векторы разных моделей несовместимы геометрически, а индекс Pinecone принимает только свою размерность.
   * *Как правильно:* Используй `dimension=1024` (стандарт по умолчанию, работает с `cohere/embed-multilingual-v3.0`, `mistral-embed`, `gemini-embedding-001`) и передавай сырой текст в `POST /vector/upsert` и `POST /vector/query` — шлюз сам вызовет совместимый 1024-мерный эмбеддер.

3. **ОШИБКА 3: Отправка `multipart/form-data` на редактирование картинок `/v1/images/edits`.**
   * *Почему падает:* Все графические методы api9 принимают JSON (`{"image": "<URL или base64>", "prompt": "..."}`). Multipart вызывает HTTP 422.
   * *Как правильно:* Передавай URL картинки или строку base64 в JSON-поле `image`.

4. **ОШИБКА 4: Принудительный выбор `provider="deepgram"` или `provider="murf"` для озвучки русского текста.**
   * *Почему плохо:* Голоса Deepgram Aura-2 и Murf по умолчанию англоязычные и читают кириллицу с сильным акцентом или транслитом.
   * *Как правильно:* Оставь `provider` пустым (шлюз сам выберет мультиязычный `elevenlabs` или русские голоса `cartesia` `sonic-3`) либо укажи `provider="elevenlabs"` / `provider="cartesia"`.

5. **ОШИБКА 5: Вызов генерации видео с `wait=0` без последующего опроса `GET /v1/video/{job_id}`.**
   * *Почему плохо:* Видео рендерится 30–120 секунд. При `wait=0` POST возвращает только `{"job_id": "...", "status": "queued"}`, ссылки `video_url` там ещё нет.
   * *Как правильно:* Либо передай `"wait": 120` в POST (шлюз сам подождёт готовности и вернёт `video_url`), либо опрашивай `GET /v1/video/{job_id}` раз в 6 секунд до `status == "completed"`.

6. **ОШИБКА 6: Неверная длительность или отсутствие картинки для Runway.**
   * *Почему падает:* В режиме текст-в-видео (`veo3.1_fast`) Runway принимает только `duration` из набора `4`, `6` или `8` секунд. А модель `gen4_turbo` работает только в режиме картинка-в-видео (требует `image_url`).
   * *Как правильно:* Для Runway без картинки ставь `duration: 4` (или `6`, `8`). Если нужен 5-секундный ролик без картинки — используй `provider="fal"` (`kling-v3`).

7. **ОШИБКА 7: Маленький `max_tokens` (например, `50` или `100`) на рассуждающих моделях (`auto:reasoning`).**
   * *Почему плохо:* Рассуждающие модели тратят первые 300–1500 токенов на внутреннюю цепочку мыслей. При малом лимите ответ обрывается с пустым `content`.
   * *Как правильно:* Для `auto:reasoning` всегда ставь `max_tokens >= 2048`.

8. **ОШИБКА 8: Отправка огромных промптов (> 6 000 токенов) в `auto:fast` или `groq`.**
   * *Почему падает:* Бесплатный лимит входного окна Groq — около 6 000–7 000 токенов на один запрос (HTTP 413).
   * *Как правильно:* Если текст длиннее ~18 000 символов кириллицы (~6 000 токенов), всегда выбирай `model="auto:long"`.

9. **ОШИБКА 9: Требование строгого `json_schema` от пинов `zhipu`, `deepseek` или `nvidia` напрямую.**
   * *Почему плохо:* `deepseek` поддерживает только `json_object`, а `zhipu` возвращает HTTP 400 на strict `json_schema`.
   * *Как правильно:* Для гарантированного JSON по схеме вызывай `POST /v1/chat/completions` с `model="auto:smart"` и полем `json_schema={...}` (шлюз сам выберет провайдера с поддержкой строгой схемы, проверит ответ валидатором и автоматически починит ошибки).

10. **ОШИБКА 10: Использование `search_document` вместо `search_query` при векторизации поискового вопроса.**
    * *Почему плохо:* Асимметричные модели (`cohere/embed-multilingual-v3.0`, `nvidia/nemotron-3-embed-1b`) кодируют документы и короткие запросы в разных режимах.
    * *Как правильно:* При индексации базы в `POST /embeddings` ставь `input_type="search_document"`, а при кодировании вопроса пользователя — `input_type="search_query"` и тот же `provider`.

11. **ОШИБКА 11: Поиск реквизитов по известному ИНН через веб-поиск вместо DaData, или отправка объекта вместо массива в `/dadata/clean/*`.**
    * *Почему плохо:* Веб-поиск медленнее и может вернуть устаревшие данные с сайтов-справочников, а Cleaner API DaData принимает на вход строго JSON-массив строк `["..."]`.
    * *Как правильно:* По ИНН/ОГРН вызывай `POST /dadata/findById/party` с `{"query": "7707083893"}`. В `/dadata/clean/address` передавай массив `["мск сухонская 11"]`.

12. **ОШИБКА 12: Короткий HTTP-таймаут клиента (например, 5–10 секунд) на тяжёлых задачах.**
    * *Почему падает:* Генерация фото (BFL/Leonardo), OCR многостраничного PDF (LlamaParse), `/enrich` и `auto:reasoning` занимают от 10 до 90 секунд.
    * *Как правильно:* Ставь таймаут HTTP-клиента **30 с** для быстрых чатов/поиска/эмбеддингов, **90 с** для фото/аудио/OCR и **180 с** для `/enrich`, `/answer` и видео с `wait`.

---

## ЧАСТЬ 2. Сравнительные таблицы таймингов (p50 / p95), качества, сильных и слабых сторон

Используй эти 5 таблиц для точного выбора метода, тира и провайдера. Оценки качества даны по 10-балльной шкале на основе живых замеров шлюза.

### Таблица 1. Текстовые тиры Router 2.0 (`POST /v1/chat/completions` и `POST /mirror/text/chat`)

| Тир (`model` / `tier`) | p50 задержка | p95 задержка | Качество (1–10) | Русский язык (1–10) | Надёжность JSON Schema | Макс. контекст | Сильные стороны (Pros) | Слабые стороны (Cons) | Когда использовать |
|---|---|---|---|---|---|---|---|---|
| `auto:flagship` | **1.0 – 3.5 с** | 12 – 25 с | **10 / 10** | **10 / 10** | 8 / 10 | 128K – 1M | Лучшие флагманы (`Nemotron-3-Ultra-550B`, `DeepSeek-V4-Pro`, `Grok-4.7`, `GPT-5.6-Sol`). Максимальная глубина и точность | Медленнее скоростных тиров; без `json_schema` не оптимизирован под миллисекундный ответ | Сложная аналитика, юриспруденция, архитектура, чистовой контент |
| `auto:reasoning` | **1.5 – 6.0 с** | 20 – 45 с | **10 / 10** | **9 / 10** | 8 / 10 | 128K | Специализированные модели рассуждений (`DeepSeek-V4-Pro`, `Grok-4.20-Reasoning`, `GPT-OSS-120B`, `Magistral`, `Command-A-Reasoning`) | Требует `max_tokens >= 2048`; высокая задержка на сложных доказательствах | Математика, финансовый аудит, поиск скрытых багов, многошаговое планирование |
| `auto:coding` | **0.35 – 1.2 с** | 4 – 10 с | **9.5 / 10** | **9 / 10** | **9 / 10** | 128K – 256K | Лидер скорости и точности кода (`Codestral-latest` ~350 мс → `DeepSeek-V4-Pro` → `GPT-5.4`) | Менее художественный стиль в обычной прозе | Генерация кода, SQL, регулярных выражений, рефакторинг, тесты |
| `auto:fast` | **0.16 – 0.45 с** | 1.2 – 2.5 с | 7.5 / 10 | 8.5 / 10 | 8.5 / 10 | до 6 000 токенов | Сверхнизкая задержка на LPU (`qwen/qwen3.8-27b` ~160 мс, `glm-4.5-flash` ~400 мс) | Жёсткий потолок входа ~6 000 токенов у головы тира (Groq) | Чат-боты реального времени, быстрая классификация, голосовые ассистенты |
| `auto:smart` | **0.4 – 1.8 с** | 5 – 12 с | **9 / 10** | **9.5 / 10** | **10 / 10** | 128K | Лучший баланс скорости, цены и 100% соблюдения JSON Schema с авто-ремонтом | Чуть уступает `flagship` в глубоких научных эссе | **Режим по умолчанию для продакшена**, парсинга, извлечения сущностей и tool-calling |
| `auto:cheap` | **0.2 – 0.8 с** | 2 – 5 с | 7.5 / 10 | 8.5 / 10 | 8 / 10 | до 6 000 токенов | Максимальная пропускная способность для фоновых задач | Не предназначен для длинных документов | Массовая категоризация, тегирование, обработка списков |
| `auto:long` | **1.2 – 4.5 с** | 15 – 35 с | **9 / 10** | **9.5 / 10** | 8.5 / 10 | **128K – 1M** | Исключает короткоконтекстные модели; гарантированно вмещает большие тексты | Выше время до первого токена на входах > 50K токенов | Анализ договоров, книг, больших дампов кода и многостраничных отчётов |

---

### Таблица 2. Детальное сравнение текстовых LLM-моделей (`<provider>/<model>`)

| Идентификатор `provider/model` | p50 / p95 | Контекст | JSON Schema | Tools | Vision | Сильные стороны | Слабые стороны | Лучший сценарий |
|---|---|---|---|---|---|---|---|---|
| `nvidia/nvidia/nemotron-3-ultra-550b-a55b` | 1.8 с / 9.0 с | 128K | Ремонт промптом | Да | Да | 550B параметров, эталонная эрудиция и системное мышление | Медленнее лёгких моделей; нет нативного strict JSON | Флагманская аналитика, сложные ТЗ и отчёты |
| `deepseek/deepseek-v4-pro` | 1.1 с / 6.0 с | 128K | `json_object` | Да | Нет | Блестящий код, логика, математика и русский язык | Не принимает картинки (`image_url`) | Сложный код, алгоритмы, логический вывод |
| `deepseek/deepseek-flash` | 0.7 с / 3.0 с | 128K | `json_object` | Да | Нет | Очень быстрый отклик при высоком интеллекте | Нет Vision | Быстрые диалоги и генерация текста |
| `openai/gpt-5.6-sol` | 1.4 с / 7.5 с | 128K | **Строгая (10/10)** | **Да** | **Да** | Эталон следования сложным инструкциям, схемам и вызовам функций | На прямом зеркале требует `temperature=1` и `max_completion_tokens` | Сложные агентные пайплайны, строгий JSON, мультимодальность |
| `openai/gpt-5.4` | 1.1 с / 5.5 с | 128K | **Строгая (10/10)** | **Да** | **Да** | Принимает любую `temperature`, быстрый и точный в коде и JSON | Чуть компактнее `gpt-5.6-sol` | Универсальный продакшен-код и структурированный вывод |
| `xai/grok-4.7` | 1.2 с / 6.0 с | 128K | Ремонт промптом | Да | Да | Живой язык, глубокие знания, отличная работа с контекстом | Реже используется для жёстких JSON-схем | Аналитика, креатив, ответы на сложные вопросы |
| `xai/grok-4.20-0309-reasoning` | 3.5 с / 18 с | 128K | Ремонт промптом | Да | Да | Глубокая верификация гипотез и математических задач | Нужен запас `max_tokens >= 2048` | Проверка доказательств, сложная логика |
| `mistral/codestral-latest` | **0.34 с / 1.5 с** | 256K | **Строгая (9/10)** | Да | Нет | Рекордная скорость генерации кода (~340 мс) и отличная работа со схемами | Специализирован на коде и структуре | Автодополнение, генерация функций, SQL, JSON |
| `mistral/mistral-medium-latest` | 0.8 с / 3.5 с | 128K | **Строгая (9/10)** | Да | Да | Отличный европейский и русский язык, поддержка Vision и JSON Schema | Уступает `Codestral` в чистой скорости кода | Деловой текст, мультимодальные задачи, JSON |
| `mistral/magistral-medium-latest` | 2.5 с / 12 с | 128K | **Строгая (9/10)** | Да | Да | Сочетает цепочку рассуждений со строгой JSON Schema | Дольше обычного `mistral-medium` | Логический анализ с выводом строго по схеме |
| `cohere/command-a-03-2025` | **0.38 с / 1.8 с** | 256K | **Строгая (9/10)** | Да | Нет | Превосходный деловой русский язык, идеальная работа в RAG без галлюцинаций | Нет Vision | RAG-синтез по документам, суммаризация, бизнес-ответы |
| `cohere/command-a-reasoning-08-2025` | 2.8 с / 14 с | 256K | **Строгая (9/10)** | Да | Нет | Рассуждающий флагман для RAG и анализа длинных отчётов | Требует `max_tokens >= 2048` | Многошаговый анализ корпоративных документов |
| `groq/qwen/qwen3.8-27b` | **0.16 с / 0.6 с** | ~6K | **Строгая (9/10)** | Да | Нет | Самая быстрая модель шлюза (~130–180 мс), грамотный русский язык | Лимит входного промпта ~6 000 токенов | Мгновенный роутинг, классификация, чат-боты |
| `groq/openai/gpt-oss-120b` | 0.25 с / 1.2 с | ~6K | **Строгая (9/10)** | Да | Нет | 120B рассуждающая модель на скорости LPU (~240 мс) | Лимит входа ~6 000 токенов | Быстрая логика и сложные инструкции на коротком входе |
| `zhipu/glm-4.5-flash` | 0.45 с / 1.8 с | 128K | `json_object` | Да | Да | Очень стабильная, быстрая модель с большим окном 128K | Не поддерживает strict `json_schema` | Длинные переводы, суммаризация, общий чат |
| `gemini/gemini-3.5-flash-lite` | 0.55 с / 2.5 с | **1M** | **Строгая (9/10)** | Да | **Да** | Огромное окно до 1 млн токенов, поддержка Vision и JSON Schema | Лаконичный стиль | Огромные документы, мультимодальный разбор |
| `perplexity/sonar` | 1.4 с / 4.5 с | 128K | Нет | Нет | Нет | Встроенный поиск в реальном времени с цитатами | Не предназначена для tool-calling | Быстрая проверка свежих фактов и новостей |

---

### Таблица 3. Аудио-модели и методы (TTS, STT, SFX, Music)

| Эндпоинт | Провайдер / Модель | p50 / p95 | Русский язык (1–10) | Сильные стороны | Слабые стороны | Когда выбирать |
|---|---|---|---|---|---|---|
| `POST /mirror/audio/tts` | `elevenlabs` / `eleven_multilingual_v2` | 0.55 с / 1.8 с | **10 / 10** | Эталонная интонация, дыхание, поддержка `stability`, `similarity_boost`, `style`, `speed` | Чуть медленнее Cartesia на длинных абзацах | **Выбор №1 для качественной русской и мультиязычной озвучки** |
| `POST /mirror/audio/tts` | `cartesia` / `sonic-3` | **0.35 с / 0.9 с** | **9.5 / 10** | Родные русские голоса (Сергей, Алексей, Дмитрий, Наталья, Дарья, Ольга), минимальная задержка | Не принимает параметры `stability`/`style` | Голосовые боты реального времени и быстрая русская речь |
| `POST /mirror/audio/tts` | `openai` / `gpt-4o-mini-tts` (и `tts-1`) | 0.9 с / 2.2 с | **9 / 10** | Чистая дикция, полная совместимость с OpenAI SDK (`POST /v1/audio/speech`) | Меньше эмоциональных настроек, чем у ElevenLabs | Стандартная интеграция через OpenAI SDK |
| `POST /mirror/audio/tts` | `fish_audio` / `speech-1.5` | 1.1 с / 2.8 с | **8.5 / 10** | Естественный тембр без фонемных артефактов | Не переключает тембр по пресетам `onyx`/`nova` | Альтернативный мультиязычный синтез |
| `POST /mirror/audio/tts` | `hume` / `octave` | 1.8 с / 3.8 с | 7.5 / 10 | Богатая актёрская эмоция | Медленнее `elevenlabs` и `cartesia` | Эмоциональные реплики (преимущественно EN) |
| `POST /mirror/audio/tts` | `deepgram` / `aura-2-*` и `murf` / `GEN2` | 0.4 с / 1.5 с | 2 / 10 (только EN!) | Идеальны для английского языка | **Не использовать для русского текста** | Озвучка строго англоязычного контента |
| `POST /mirror/audio/stt` | `groq` / `whisper-large-v3-turbo` | **0.42 с / 1.1 с** | **10 / 10** | Мгновенная и точная расшифровка русской и английской речи | Только распознавание (без диаризации по ролям) | **Выбор №1 для распознавания голосовых сообщений и звонков** |
| `POST /mirror/audio/stt` | `elevenlabs` / `scribe_v1` | 0.6 с / 1.8 с | **10 / 10** | 99 языков, высокая устойчивость к шуму | Чуть медленнее Groq | Сложные записи с акцентами и фоновым шумом |
| `POST /mirror/audio/stt` | `deepgram` / `nova-2` | 0.9 с / 2.2 с | **9 / 10** | Умная пунктуация (`smart_format=true`), работа по прямой ссылке `audio_url` | Чуть уступает Whisper на редких русских фамилиях | Потоковая и файловая транскрибация по URL |
| `POST /mirror/audio/stt` | `assemblyai` / `universal` | 2.2 с / 5.5 с | **9 / 10** | Отлично справляется с длинными файлами | Асинхронная загрузка+опрос внутри вызова (~2.5 с) | Длинные интервью и совещания |
| `POST /mirror/audio/sfx` | `elevenlabs` / `eleven_sound_generation_v1` | 1.5 с / 3.5 с | — (промт на EN) | Генерация любых звуков, эмбиента и спецэффектов (0.5–22 с) | Промпт рекомендуется писать на английском | Озвучка видео, игр, уведомлений и атмосферных сцен |
| `POST /mirror/audio/music` | `elevenlabs` (`music_v2`) / `stability` (`stable-audio-2.5`) | 3.0 с / 8.0 с | — | Полноценные музыкальные треки и джинглы в MP3 (до 10 минут) | Высокое время генерации на длинных треках | Фоновая музыка для роликов, подкастов и презентаций |

---

### Таблица 4. Изображения и Видео (Генерация, Редактирование, Удаление фона, Апскейл, Видео)

| Эндпоинт | Провайдер / Модель | p50 / p95 | Фотореализм | Текст на картинке | Сильные стороны | Слабые стороны | Когда выбирать |
|---|---|---|---|---|---|---|---|
| `POST /mirror/image/generate` | `clipdrop` / `clipdrop-sdxl-1.0` | **1.8 с / 4.2 с** | 8.5 / 10 | 6 / 10 | Самая быстрая генерация чистых PNG | Игнорирует `aspect_ratio` (всегда 1:1) и `negative_prompt` | Быстрые иллюстрации, иконки, аватарки 1:1 |
| `POST /mirror/image/generate` | `recraft` / `recraftv3` | 3.5 с / 7.5 с | **10 / 10** | **10 / 10** | **№1 в мире по фотореализму, дизайну и точным надписям на картинке** | Чуть дольше ClipDrop | Рекламные баннеры, постеры с текстом, продуктовый дизайн |
| `POST /mirror/image/generate` | `bfl` / `flux-pro-1.1` | 5.0 с / 12 с | **10 / 10** | **9.5 / 10** | Флагман Black Forest Labs FLUX 1.1 Pro, кинематографический свет | Синхронный поллинг занимает ~5–10 с | Художественные и студийные фотографии высшего класса |
| `POST /mirror/image/generate` | `ideogram` / `V_2_TURBO` | 4.0 с / 9.0 с | 9 / 10 | **10 / 10** | Идеальная типографика, логотипы, плакаты, все `aspect_ratio` | Меньше подходит для макро-текстур | Логотипы, обложки, карточки товаров с надписями |
| `POST /mirror/image/generate` | `stability` / `stable-image-core` | 3.2 с / 7.0 с | 9 / 10 | 7.5 / 10 | Поддерживает все `aspect_ratio`, `negative_prompt` и `webp`/`jpeg`/`png` | Слабее Recraft/Ideogram в длинных надписях | Универсальная фотогенерация с `negative_prompt` |
| `POST /mirror/image/generate` | `leonardo` (`leonardo-phoenix`), `bria` (`bria-2.3`), `openai` (`gpt-image-1-mini`) | 4.5 с / 11 с | 9 / 10 | 8.5 / 10 | Отличное понимание сложных композиционных промптов | У `openai` размер фиксирован `1024x1024` | Сложные многообъектные сцены |
| `POST /mirror/image/edit` | `stability` (`sd3.5-large`), `clipdrop` (`replace-bg`), `bfl` (`flux-kontext-pro`), `gemini` (`2.5-flash-image`) | 3.5 с / 12 с | **9.5 / 10** | 8 / 10 | Семантическое изменение объектов, стиля или замена фона по тексту | Принимает только JSON (`image` + `prompt`) | Редактирование фото товара, смена фона и освещения |
| `POST /mirror/image/remove-bg` | `clipdrop` → `stability` → `bria` | **1.2 с / 3.5 с** | — | — | Идеальная обтравка волос и мелких деталей в прозрачный PNG | — | Каталоги товаров, маркетплейсы, портреты |
| `POST /mirror/image/upscale` | `clipdrop` (до 4096×4096), `bria` (2x), `stability` | 2.0 с / 6.0 с | — | — | Повышение разрешения без мыла и артефактов JPEG | Точные `target_width`/`target_height` задаются на `clipdrop` | Подготовка изображений к печати и 4K-экранам |
| `POST /infographic` | LLM SVG Generator | 4.0 с / 12 с | Вектор SVG | **10 / 10** | Возвращает чистый масштабируемый `<svg viewBox="0 0 1200 675">` на русском языке | Это векторная схема/диаграмма, а не растровое фото | Дашборды, презентации, визуализация статистики |
| `POST /mirror/video/generate` | `fal` (`kling-v3`), `runway` (`veo3.1_fast` / `gen4_turbo`), `luma` (`ray-2`), `zhipu` (`cogvideox-flash`) | **35 с / 110 с** | **9.5 / 10** | — | Кинематографическое видео 720p/1080p из текста или стартового кадра `image_url` | Асинхронный процесс: требует `wait=60..240` или поллинга `GET /v1/video/{job_id}` | Видеокреативы, анимация фото товаров, сторис |

---

### Таблица 5. Веб-поиск, Скрейпинг, OCR, B2B-обогащение, DaData и Векторный RAG

| Эндпоинт | p50 / p95 | Вход | Выход | Сильные стороны | Слабые стороны / Ограничения | Когда выбирать |
|---|---|---|---|---|---|---|
| `POST /search` (и `/mirror/search`) | **0.45 с / 1.6 с** | `query`, `country`, `lang`, `hedge`, `merge`, `days` | `results[{title, url, content, domain, kind, rank}]` | Авто-RU гео для кириллицы, параллельный `hedge=2`, `merge=true` по консенсусу, разметка типа сайта (`kind`: `registry`, `procurement`, `courts`, `social`, `web`), безотказный фолбэк | Возвращает сниппеты, а не полный текст страниц | Быстрый поиск фактов, новостей и ссылок |
| `POST /search/company` | 1.2 с / 3.5 с | `name`, `inn`, `city`, `domain`, `facets` | `facets`, `by_kind`, `official_site_candidates` | Одним вызовом параллельно ищет официальный сайт, реестры, контакты, соцсети, суды и закупки | Не заменяет полное чтение текста сайта | **Поиск официального сайта и цифрового следа компании** |
| `POST /answer` | 4.5 с / 14 с | `query`, `max_results`, `scrape_top` | `{answer, sources, x_provider, x_model}` | Сам ищет в вебе, скачивает топ-страницы (`scrape_top`) и пишет точный ответ со ссылками | Медленнее обычного `/search` из-за чтения страниц и синтеза | Ответы на сложные вопросы, требующие актуальных данных из интернета |
| `POST /scrape` | **0.5 с / 3.5 с** | `url` | `{provider, url, content}` (Markdown) | Прямой быстрый фетч + 7 облачных скрейперов (`Firecrawl`, `Tavily`, `ScrapingBee`, `Apify`, `Jina`) + кэш 6 ч | При полностью мёртвом сайте возвращает `unreachable: true` (проверяй этот флаг!) | Чтение полной веб-страницы в чистый Markdown |
| `POST /v1/ocr` (и `/ocr`) | **3.5 с / 9.0 с** | `document_url`, `image_url` или `document_b64` | `{provider, model, text, pages[{index, markdown}]}` | Сохраняет структуру таблиц и реквизитов в Markdown (`Mistral OCR` + `LlamaParse`) | Таймаут клиента должен быть не менее 60 с | Распознавание PDF-договоров, счетов, УПД, выписок и сканов |
| `POST /extract` | 1.8 с / 8.5 с | `json_schema` + `text` (или `document_url`/`image_url`) | `{data, schema_valid, parse_error}` | Если передан `document_url`/`image_url`, **сам делает OCR**, затем извлекает JSON со строгой валидацией и auto-repair | Текст усекается до 20 000 символов | Превращение любого сырого текста, PDF или фото чека в типизированный JSON |
| `POST /enrich` | 12 с / 45 с | `inn`, `name`, `url`, `category` (или `categories`) | `{data, sources, x_cached}` | **Комбайн B2B-обогащения:** мгновенно подтягивает ЕГРЮЛ из DaData (ИНН, ОГРН, ФИО руководителя), ищет в вебе, параллельно скрейпит топ-5 сайтов, объединяет regex-контакты с LLM-извлечением (20 категорий) | Высокое время выполнения на холодном кэше (ставь таймаут 120–180 с) | Полное обогащение карточки компании одним вызовом |
| `POST /dadata/{path}` | **0.12 с / 0.45 с** | Нативное тело DaData | Нативный JSON DaData | Мгновенный доступ к ЕГРЮЛ/ЕГРИП (`findById/party`, `suggest/party`), ФИАС (`suggest/address`), банкам и стандартизации (`clean/*`) | В `clean/*` тело должно быть JSON-массивом `["..."]` | Точная проверка ИНН/ОГРН, ФИО директора, адреса и телефона |
| `POST /v1/embeddings` и `POST /embeddings` | **0.18 с / 0.65 с** | `input` / `texts`, `provider`, `input_type` | Векторы `1024-d` (`cohere`, `mistral`, `gemini`), `1536-d` (`openai`, `openrouter`), `2048-d` (`nvidia`), `512-d` (`voyage`) | Автоматическое чередование провайдеров, поддержка `search_document` / `search_query` | Не смешивай векторы разных провайдеров в одной базе | Векторизация текстов, семантический поиск, дедупликация |
| `POST /rerank` | **0.22 с / 0.65 с** | `query`, `documents[]`, `top_n` | `results[{index, score, document}]` | Кросс-энкодер (`Cohere rerank-v3.5`, `Voyage rerank-2-lite`, `Jina v2`) кратно повышает точность RAG | Принимает до ~50–100 кандидатов за вызов | Финальная сортировка чанков перед подачей в LLM |
| `GET /vector/indexes`, `POST /vector/upsert`, `POST /vector/query` | **0.35 с / 1.2 с** | `items[{id, text, metadata}]` / `query`, `namespace`, `dimension` | Готовая запись и семантический поиск в Pinecone | **Сам считает эмбеддинги** нужной размерности (`1024-d` по умолчанию) при записи и поиске | Всегда передавай один и тот же `namespace` и `dimension` | Долговременная векторная память агента и корпоративный RAG |

---

## ЧАСТЬ 3. Подробный справочник методов и примеры кода

Ниже приведены точные схемы запросов и ответов по каждому направлению.

---

### 3.1. Текстовая генерация, Чат, SSE-стриминг и Инструменты

#### `POST /v1/chat/completions` (OpenAI-совместимый стандарт)

Полная совместимость с `OpenAI(base_url="https://api9.ru/v1")`. Поддерживает потоковую передачу `stream: true` (`text/event-stream`), вызов функций (`tools`, `tool_choice`), мультимодальный вход (`image_url` внутри `messages`), строгую валидацию JSON (`json_schema`, `json_mode`, `validate`, `repair`), фильтрацию по возможностям (`require: ["vision", "json_schema", "tools"]`) и кэширование идентичных запросов (`cache: true`).

```python
from openai import OpenAI

client = OpenAI(base_url="https://api9.ru/v1", api_key="YOUR_API_KEY")

# 1. Вызов с проверкой JSON Schema
resp = client.chat.completions.create(
    model="auto:smart",
    messages=[{"role": "user", "content": "Выдели реквизиты: ООО Ромашка, ИНН 7707083893, Москва"}],
    extra_body={
        "json_schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "inn": {"type": "string"},
                "city": {"type": "string"},
            },
            "required": ["name", "inn", "city"],
        }
    },
)
print(resp.choices[0].message.content)
```

#### `POST /mirror/text/chat` (Умный роутер по тирам)

Принимает либо `prompt` + `system`, либо массив `messages`, а также `tier` (`"flagship"`, `"reasoning"`, `"coding"`, `"fast"`, `"smart"`, `"cheap"`, `"long"`), `provider`, `model`, `max_tokens`, `temperature` и `stream` (`true`/`false`).

```bash
curl -sS https://api9.ru/mirror/text/chat \
  -H "Authorization: Bearer $API9_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Напиши потокобезопасный LRU-кэш на Python с декоратором.",
    "tier": "coding",
    "max_tokens": 1000
  }'
```

#### Прикладные текстовые методы

| Метод и путь | Параметры тела (JSON) | Что возвращает |
|---|---|---|
| `POST /text` | `prompt` (обяз.), `system`, `tier`, `provider`, `model`, `json_schema`, `json_mode`, `max_tokens`, `temperature` | `{provider, model, content, text, parsed, latency_ms}` |
| `POST /chat` | `messages` (обяз.), `tier`, `provider`, `model`, `json_schema`, `json_mode`, `max_tokens`, `temperature` | `{provider, model, content, text, parsed, latency_ms}` |
| `POST /article` | `topic` (обяз.), `words` (600), `lang` (`"ru"`), `ground` (`true` — поиск фактов в вебе), `provider` | `{provider, model, article, sources, grounded}` |
| `POST /translate` | `text` (обяз.), `to_lang` (`"ru"`), `from_lang` (авто) | `{provider, model, content}` |
| `POST /summarize` | `text` (обяз.), `sentences` (3), `lang` (`"ru"`) | `{provider, model, content}` |
| `POST /rewrite` | `text` (обяз.), `tone` (`"neutral"`), `instruction`, `lang` (`"ru"`) | `{provider, model, content}` |
| `POST /seo` | `topic` (обяз.), `lang` (`"ru"`) | `{provider, model, content}` (JSON с `title`, `description`, `keywords`, `slug`) |
| `POST /headlines` | `topic` (обяз.), `count` (7), `lang` (`"ru"`) | `{provider, model, content}` |
| `POST /social` | `topic` (обяз.), `platform` (`"telegram"`, `"vk"`, `"instagram"`, `"linkedin"`), `count` (3), `lang` (`"ru"`) | `{provider, model, content}` |
| `POST /v1/moderations` | `input` (строка или массив строк), `model` (`"auto"`) | `{id, model, results[{flagged, categories, category_scores}], x_provider}` |
| `POST /v1/batch` | `requests` (до 500 элементов `{"endpoint": "/text"|"/chat"|"/search"|"/embeddings"|"/rerank"|"/summarize"|"/translate"|"/extract", "body": {...}}`), `concurrency` (1..128) | `{count, ok, results[{ok, endpoint, result, error}]}` |
| `POST /v1/benchmark` | `modality` (`"text"`, `"image"`, `"search"`, `"embeddings"`, `"tts"`, `"rerank"`), `prompt`, `max_providers` (8) | `{modality, count, ok, results[{provider, ok, latency_ms, model, output}]}` |
| `GET /v1/models` | — | Список всех 120+ моделей и тиров в формате OpenAI |

---

### 3.2. Аудио: Синтез речи (TTS), Распознавание (STT), Звуковые эффекты (SFX) и Музыка

#### `POST /mirror/audio/tts` (и `/v1/audio/speech`, `/voice`)

* **Универсальные гендерные пресеты голосов (`voice` / `voice_id`):**
  * **Мужские голоса:** `onyx` (глубокий баритон), `echo` (уверенный мужской), `fable` (тёплый рассказчик).
  * **Женские голоса:** `nova` (спокойный женский), `shimmer` (выразительный женский), `alloy` (чистый женский).
* **Формат ответа (`output`):** `"json"` (по умолчанию — `{"provider", "model", "audio_b64", "format": "mp3"}`) или `"binary"` (сырой поток `audio/mpeg`).
* **Тонкие настройки (для ElevenLabs):** `stability` (0.5), `similarity_boost` (0.78), `style` (0.22), `speed` (0.7..1.2).

```python
import base64, requests

# 1. JSON-режим с авто-ротацией лучших русских голосов
r = requests.post(
    "https://api9.ru/mirror/audio/tts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "Здравствуйте! Ваш заказ успешно оформлен.", "voice": "nova", "output": "json"},
    timeout=60,
)
data = r.json()
open("greeting.mp3", "wb").write(base64.b64decode(data["audio_b64"]))
```

#### `POST /mirror/audio/stt` (и `/transcribe`, `/v1/audio/transcriptions`)

* `POST /mirror/audio/stt` и `POST /transcribe` принимают JSON: `{"audio_url": "https://...", "language": "ru"}` или `{"audio_b64": "...", "language": "ru"}`.
* `POST /v1/audio/transcriptions` принимает `multipart/form-data` (`file`, `model="whisper-1"`, `language="ru"`) — полностью совместимо с `client.audio.transcriptions.create(...)` в OpenAI SDK.

#### `POST /mirror/audio/sfx` и `POST /mirror/audio/music`

* **SFX (`POST /mirror/audio/sfx`):** `{"prompt": "gentle rain on a window and distant thunder", "duration_seconds": 5.0, "prompt_influence": 0.35, "output": "json"}`.
* **Музыка (`POST /mirror/audio/music` и `POST /v1/music`):** `{"prompt": "upbeat electronic synthwave track, 120 bpm, no vocals", "duration_ms": 30000, "output": "json"}`.

---

### 3.3. Изображения и Видео

#### Генерация картинок: `POST /mirror/image/generate` (и `/v1/images/generations`, `/image`)

* **Параметры:** `prompt` (рекомендуется на английском), `aspect_ratio` (`"1:1"`, `"16:9"`, `"9:16"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`), `output_format` (`"png"`, `"jpeg"`, `"webp"`), `negative_prompt`, `provider` (пусто = авто), `model`, `output` (`"json"` или `"binary"`).
* **Ответ JSON:** `{"provider": "recraft", "model": "recraftv3", "image_b64": "...", "format": "png"}`.

#### Редактирование, Удаление фона и Апскейл

* **Редактирование (`POST /mirror/image/edit`, `POST /v1/images/edits`):** `{"image": "<URL или base64>", "prompt": "replace background with a minimalist white studio", "strength": 0.65, "output": "json"}`.
* **Удаление фона (`POST /mirror/image/remove-bg`):** `{"image": "<URL или base64>", "output": "json"}` → возвращает прозрачный PNG.
* **Супер-разрешение (`POST /mirror/image/upscale`):** `{"image": "<URL или base64>", "target_width": 2048, "target_height": 2048, "output": "json"}`.
* **SVG-инфографика (`POST /infographic`):** `{"topic": "Структура выручки по кварталам", "data_points": ["Q1: 12 млн ₽", "Q2: 18 млн ₽", "Q3: 24 млн ₽"]}` → возвращает `{"svg": "<svg ...>...</svg>"}`.

#### Генерация видео: `POST /mirror/video/generate` (и `POST /v1/video`, `GET /v1/video/{job_id}`)

```python
import time, requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Вариант А: Подождать готовности прямо внутри запроса (wait=120 секунд)
r = requests.post(
    "https://api9.ru/mirror/video/generate",
    headers=headers,
    json={
        "prompt": "A cinematic drone shot over a futuristic glass city at sunset",
        "aspect_ratio": "16:9",
        "duration": 5,
        "wait": 120,
    },
    timeout=180,
).json()

# Вариант Б: Если ролик ещё рендерится (status == "processing"), дождаться через GET
job_id = r.get("job_id")
while r.get("status") not in ("completed", "error") and job_id:
    time.sleep(6)
    r = requests.get(f"https://api9.ru/v1/video/{job_id}", headers=headers, timeout=30).json()

print("Готовое видео:", r.get("video_url"))
```

---

### 3.4. Веб-поиск, Скрейпинг, OCR, Извлечение данных и DaData

#### Поиск и аналитика: `POST /search`, `POST /search/company`, `POST /answer`

* **`POST /search`:** `{"query": "закупки серверного оборудования", "max_results": 5, "country": "ru", "lang": "ru", "hedge": 2, "merge": true}`. Каждый результат содержит `title`, `url`, `content`, `domain`, `kind` (`registry` | `procurement` | `courts` | `aggregator` | `marketplace` | `jobs` | `social` | `news` | `wiki` | `web`) и `rank`.
* **`POST /search/company`:** `{"name": "СКБ Контур", "inn": "6663003127", "city": "Екатеринбург"}` → возвращает результаты, сгруппированные по фасетам (`official`, `registry`, `contacts`, `socials`) и массив `official_site_candidates`.
* **`POST /answer`:** `{"query": "Какие основные направления деятельности у ПАО Сбербанк?", "max_results": 5, "scrape_top": 3}` → возвращает `{answer, sources[{title, url}]}`.

#### Скрейпинг, OCR и Извлечение JSON: `POST /scrape`, `POST /v1/ocr`, `POST /extract`

* **`POST /scrape`:** `{"url": "https://example.com"}` → `{"provider": "direct", "url": "...", "content": "# Example Domain..."}`.
* **`POST /v1/ocr`:** `{"document_url": "https://example.com/invoice.pdf"}` (или `image_url`, или `document_b64`) → `{"provider": "mistral", "model": "mistral-ocr-latest", "text": "...", "pages": [{"index": 0, "markdown": "..."}]}`.
* **`POST /extract`:** принимает `json_schema` и `text` (или `document_url` / `image_url` — тогда сначала автоматически выполняется OCR) и возвращает строго провалидированный объект в поле `data` (`schema_valid: true`).

#### Обогащение компаний (`POST /enrich`) и прямое зеркало DaData (`/dadata/{path}`)

* **`POST /enrich`:**
  ```bash
  curl -sS https://api9.ru/enrich \
    -H "Authorization: Bearer $API9_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "inn": "7707083893",
      "name": "Сбербанк",
      "categories": ["requisites", "contacts"]
    }'
  ```
  Автоматически опрашивает ЕГРЮЛ (DaData), ищет официальный сайт, скрейпит страницы и извлекает структурированные поля (`legal_name`, `inn`, `kpp`, `ogrn`, `okpo`, `okved_main`, `ceo`, `phones`, `emails`, `messengers`).
* **Прямой доступ к DaData (`POST /dadata/{path}`):**
  * Поиск по ИНН/ОГРН: `POST /dadata/findById/party` с телом `{"query": "7707083893", "branch_type": "MAIN"}`.
  * Подсказки по названию/адресу/банку/ФИО: `POST /dadata/suggest/party`, `POST /dadata/suggest/address`, `POST /dadata/suggest/bank`, `POST /dadata/suggest/fio` с телом `{"query": "..."}`.
  * Стандартизация (Cleaner): `POST /dadata/clean/address`, `POST /dadata/clean/phone`, `POST /dadata/clean/name`, `POST /dadata/clean/passport` с телом-массивом `["..."]`.

---

### 3.5. Векторные эмбеддинги, Реранк, Векторная БД (`/vector/*`) и Нативные зеркала (`/mirror/{provider}/{path}`)

#### Векторная база данных с авто-эмбеддингом (`/vector/*`)

Вам не нужно вручную считать векторы перед записью или поиском — достаточно передать поле `text` в `POST /vector/upsert` и текстовый `query` в `POST /vector/query`:

```python
import requests

H = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. Запись документов (текст автоматически векторизуется в 1024 измерения!)
requests.post(
    "https://api9.ru/vector/upsert",
    headers=H,
    json={
        "namespace": "my_knowledge_base",
        "dimension": 1024,
        "items": [
            {"id": "doc-1", "text": "Возврат оборудования возможен в течение 14 дней по заявлению.", "metadata": {"category": "policy"}},
            {"id": "doc-2", "text": "Отгрузка насосов со склада в Казани осуществляется ежедневно до 16:00.", "metadata": {"category": "logistics"}},
        ],
    },
    timeout=60,
).raise_for_status()

# 2. Семантический поиск по смыслу
res = requests.post(
    "https://api9.ru/vector/query",
    headers=H,
    json={
        "namespace": "my_knowledge_base",
        "dimension": 1024,
        "query": "В какие часы работает отгрузка в Казани?",
        "top_k": 3,
    },
    timeout=60,
).json()

for m in res["matches"]:
    print(m["id"], round(m["score"], 4), m["metadata"].get("text"))
```

#### Нативные зеркала 60+ провайдеров (`/mirror/{provider}/{native-path}`)

Если вашему агенту нужен специфический нативный эндпоинт конкретного провайдера (например, `POST /mirror/anthropic/v1/messages`, `POST /mirror/cohere/v2/rerank`, `POST /mirror/openai/chat/completions`, `POST /mirror/elevenlabs/v1/voices`, `GET /mirror/hunter/account`, `GET /mirror/kontur_focus/req?inn=7707083893`), вызывайте `https://api9.ru/mirror/{provider}/{path}` со своим обычным заголовком `Authorization: Bearer <YOUR_API_KEY>`. Шлюз сам подставит нативную авторизацию целевого сервиса, обработает стриминг (`text/event-stream`) и при необходимости переключит запрос на резервный канал.