Документация api9 для разработчиков и ИИ-агентов
Единый высокоскоростной шлюз (Router 2.0) ко всем современным генеративным и аналитическим ИИ-моделям под одним заголовком Authorization: Bearer <YOUR_API_KEY>.
Для автоматического чтения ИИ-агентами доступна чистая Markdown-версия со всеми таблицами роутинга и таймингов по ссылке https://api9.ru/usage.md.
AGENT GUIDE
Алгоритм выбора метода (Foolproof Decision Tree для ИИ-агентов)
Правила ЕСЛИ → ТО
ИИ-агент должен выбирать ровно один маршрут по первому совпавшему условию сверху вниз:
| Если задача агента… | Какой метод вызывать | Обязательные параметры и правила |
|---|---|---|
| Быстрый ответ / чат (вход ≤ 6 000 токенов) | POST /v1/chat/completions | model="auto:fast", messages=[...] (отклик ~160–350 мс) |
| Максимальное качество текста / сложная аналитика | POST /v1/chat/completions | model="auto:flagship" (Nemotron-3-Ultra-550B / DeepSeek-V4-Pro / Grok-4.7 / GPT-5.6-Sol) |
| Математика, логика, цепочка доказательств | POST /v1/chat/completions | model="auto:reasoning", max_tokens ≥ 2048 |
| Написание, рефакторинг или отладка кода | POST /v1/chat/completions | model="auto:coding" (Codestral-latest ~340 мс → DeepSeek-V4-Pro → GPT-5.4) |
| Строгий JSON по схеме (JSON Schema) | POST /v1/chat/completions | model="auto:smart", json_schema={...} (не передавать temperature!) |
| Большой документ / промпт (> 6 000 токенов) | POST /v1/chat/completions | model="auto:long" (контекст 128K–1M токенов) |
| Сгенерировать картинку с нуля | POST /mirror/image/generate | prompt="..." (на английском); для текста на картинке: provider="recraft" или "ideogram" |
| Изменить картинку / удалить фон / 4K-апскейл | POST /mirror/image/editPOST /mirror/image/remove-bgPOST /mirror/image/upscale | image="<URL или base64>" (строго JSON, не multipart!) |
| Сгенерировать видеоролик (текст/фото → MP4) | POST /mirror/video/generate | prompt="...", wait=120 (или wait=0 + опрос GET /v1/video/{job_id}) |
| Озвучить текст голосом (TTS) | POST /mirror/audio/tts | text="...", voice="onyx" (муж.) или "nova" (жен.), provider не указывать для RU |
| Распознать речь в текст (STT) | POST /mirror/audio/stt | audio_url="..." (или audio_b64), language="ru" |
| Звуковой эффект (SFX) / Музыка (MP3) | POST /mirror/audio/sfxPOST /mirror/audio/music | SFX: prompt (EN), duration_seconds=5. Музыка: prompt, duration_ms=30000 |
| Найти ссылки / официальный сайт компании | POST /searchPOST /search/company | Поиск с авто-RU гео, консенсусом merge=true и разметкой kind |
| Ответить на вопрос по свежим данным из веба | POST /answer | query="...", scrape_top=3 (поиск + скрейп + ответ с цитатами) |
| Скачать страницу в Markdown / Распознать PDF | POST /scrapePOST /v1/ocr | Скрейп: url. OCR таблиц и сканов: document_url или image_url |
| Извлечь типизированный JSON из текста или PDF | POST /extract | json_schema={...} + text или document_url (авто-OCR + валидация) |
| Получить реквизиты ЕГРЮЛ по ИНН / Полное досье | POST /dadata/findById/partyPOST /enrich | DaData: {"query":"7707083893"} (~130 мс). Полное веб+ЕГРЮЛ досье: POST /enrich |
| Векторная память (Pinecone) и Реранк (RAG) | POST /vector/upsertPOST /vector/queryPOST /rerank | dimension=1024, namespace="..." (текст векторизуется автоматически!) |
CHECKLIST
12 фатальных ошибок глупых агентов и как их избежать
Анти-паттерны
| № | Частая ошибка агента | Почему это ломает запрос | Правильное решение |
|---|---|---|---|
1 | Передача temperature != 1 или max_tokens в gpt-5.6-sol на прямом зеркале | Модели OpenAI серии gpt-5.6-sol / o3 отвергают эти поля с HTTP 400 | Вызывай через POST /v1/chat/completions или POST /mirror/text/chat — шлюз сам нормализует параметры |
2 | Смешивание размерностей векторов (512, 1024, 1536, 2048) в одном индексе | Индекс принимает только свою размерность, а векторы разных моделей несовместимы | Используй dimension=1024 (Cohere / Mistral / Gemini) или передавай сырой text в /vector/upsert и /vector/query |
3 | Отправка multipart/form-data на /v1/images/edits | Графические эндпоинты принимают JSON, multipart даёт HTTP 422 | Передавай URL или base64 в JSON-поле "image" |
4 | Выбор provider="deepgram" или "murf" для русской озвучки (TTS) | Их голоса англоязычные и читают кириллицу транслитом | Оставь provider пустым или укажи "elevenlabs" / "cartesia" |
5 | Вызов POST /v1/video с wait=0 без поллинга результата | При wait=0 возвращается только job_id в статусе queued | Либо ставь "wait": 120 в POST, либо опрашивай GET /v1/video/{job_id} каждые 6 с |
6 | Передача duration: 5 в Runway text-to-video или вызов gen4_turbo без картинки | Runway t2v принимает только 4, 6, 8 с, а gen4_turbo требует image_url | Для Runway t2v ставь duration: 4; для 5-секундного t2v выбирай provider="fal" |
7 | Маленький max_tokens (< 200) на auto:reasoning | Бюджет тратится на скрытую цепочку мыслей, content приходит пустым | Для auto:reasoning всегда ставь max_tokens ≥ 2048 |
8 | Отправка длинного текста (> 6 000 токенов) в auto:fast или groq | Входное окно головы скоростного тира ограничено ~6 000 токенов (HTTP 413) | При длине текста > 18 000 символов всегда выбирай model="auto:long" |
9 | Запрос строгого json_schema от пинов zhipu или deepseek напрямую | zhipu отдаёт 400 на strict schema, а deepseek знает только json_object | Используй model="auto:smart" или пины openai/gpt-5.4, mistral/codestral-latest, cohere/command-a-03-2025 |
10 | Кодирование вопроса с input_type="search_document" вместо "search_query" | Асимметричные модели (Cohere, NVIDIA) теряют точность поиска | Документы индексируй с search_document, а поисковый вопрос — с search_query |
11 | Отправка объекта {"query":...} в /dadata/clean/* | Cleaner API DaData ожидает JSON-массив строк ["..."] | В /dadata/clean/address и clean/phone передавай массив: ["мск сухонская 11"] |
12 | Короткий HTTP-таймаут клиента (5–10 с) на тяжёлых методах | Генерация фото, OCR PDF, /enrich и видео длятся 10–90 с | Ставь таймаут 30 с для чата/поиска, 90 с для фото/аудио/OCR и 180 с для /enrich и видео |
BENCHMARKS
Таблицы сравнений таймингов (p50 / p95), качества, плюсов и минусов моделей
Матрица роутинга
1. Текстовые тиры и ведущие LLM-модели
| Модель / Тир | p50 / p95 | Контекст | Качество / RU | JSON Schema | Сильные стороны (+) | Слабые стороны (−) |
|---|---|---|---|---|---|---|
auto:flagship | 1.0 с / 15 с | 128K–1M | 10 / 10 | 8 / 10 | Максимальный интеллект (Nemotron-550B, DeepSeek-V4-Pro, Grok-4.7, GPT-5.6-Sol) | Выше задержка, чем у fast и coding |
auto:reasoning | 1.8 с / 30 с | 128K | 10 / 9.5 | 8 / 10 | Глубокая логика, математика, планирование (DeepSeek-V4-Pro, Grok-4.20, GPT-OSS-120B, Magistral) | Требует max_tokens ≥ 2048 |
auto:coding | 0.35 с / 2.5 с | 128K–256K | 9.5 / 9.0 | 9 / 10 | Сверхбыстрая генерация кода (codestral-latest ~340 мс → deepseek-v4-pro) | Менее художественный стиль в обычной прозе |
auto:fast | 0.16 с / 0.9 с | ~6K | 7.5 / 8.5 | 8.5 / 10 | Мгновенный отклик LPU (groq/qwen/qwen3.8-27b ~160 мс, glm-4.5-flash) | Потолок входа ~6 000 токенов |
auto:smart | 0.45 с / 4.0 с | 128K | 9.0 / 9.5 | 10 / 10 | Эталон для продакшена: авто-проверка и авто-ремонт JSON Schema | Чуть уступает flagship в длинных научных текстах |
auto:long | 1.5 с / 20 с | 128K–1M | 9.0 / 9.5 | 8.5 / 10 | Безопасно переваривает большие договоры, книги и дампы кода | Выше задержка на входах > 50K токенов |
nvidia/nvidia/nemotron-3-ultra-550b-a55b | 1.8 с / 9.0 с | 128K | 10 / 9.5 | Ремонт | Крупнейшая 550B модель, системная архитектура и аналитика | Нет нативного strict JSON |
deepseek/deepseek-v4-pro | 1.1 с / 6.0 с | 128K | 10 / 10 | json_object | Лучшее соотношение интеллекта в коде, логике и русском языке | Не принимает изображения (image_url) |
openai/gpt-5.6-sol & gpt-5.4 | 1.2 с / 6.5 с | 128K | 10 / 10 | Строгая (10/10) | Безупречный JSON Schema, сложные tools и Vision | gpt-5.6-sol фиксирует temperature=1 |
xai/grok-4.7 & grok-4.20-0309-reasoning | 1.2 с / 8.0 с | 128K | 9.5 / 9.5 | Ремонт | Свежие знания, сильная аргументация, поддержка Vision | Реже используется для строгих JSON-схем |
cohere/command-a-03-2025 | 0.38 с / 1.8 с | 256K | 9.0 / 9.5 | Строгая (9/10) | Точный деловой русский язык, минимум галлюцинаций в RAG | Нет Vision |
gemini/gemini-3.5-flash-lite | 0.55 с / 2.5 с | 1M | 8.5 / 9.0 | Строгая (9/10) | Окно 1 млн токенов + Vision + быстрая выдача | Лаконичный стиль |
2. Аудио, Изображения, Видео, Поиск, OCR, DaData и Векторный RAG
| Направление и метод | Ведущие провайдеры / модели | p50 / p95 | Сильные стороны (+) | Ограничения и правила роутинга (−) |
|---|---|---|---|---|
TTS (Озвучка)POST /mirror/audio/tts | elevenlabs (eleven_multilingual_v2), cartesia (sonic-3), openai (gpt-4o-mini-tts), fish_audio | 0.35 с – 0.9 с | Живая русская интонация, пресеты onyx/echo/fable (муж.) и nova/shimmer/alloy (жен.) | Не указывать deepgram и murf для кириллицы (они англоязычные) |
STT (Распознавание)POST /mirror/audio/stt | groq (whisper-large-v3-turbo), elevenlabs (scribe_v1), deepgram (nova-2), assemblyai | 0.42 с – 1.5 с | Точная русская и английская транскрибация за доли секунды | Передавать language="ru" для повышения точности |
SFX и МузыкаPOST /mirror/audio/sfxPOST /mirror/audio/music | elevenlabs (sound-generation, music_v2), stability (stable-audio-2.5) | 1.5 с – 6.0 с | Генерация любых фоновых звуков (0.5–22 с) и музыкальных треков (до 10 мин) в MP3 | Промпт для SFX лучше писать на английском |
Генерация фотоPOST /mirror/image/generate | clipdrop (~1.8 с), recraft (recraftv3), bfl (flux-pro-1.1), ideogram, stability, leonardo, bria, openai | 1.8 с – 7.5 с | Фотореализм студийного уровня; recraft и ideogram идеально рисуют текст | Промпт писать на английском; текст для надписи брать в кавычки |
Редактирование / Фон / Апскейл/mirror/image/edit|remove-bg|upscale | stability, clipdrop, bfl (flux-kontext-pro), bria, gemini | 1.2 с – 6.0 с | Мгновенное удаление фона, апскейл до 4096×4096 и семантическая правка | Передавать image как URL или base64 в JSON |
ВидеоPOST /mirror/video/generate | fal (kling-v3), runway (veo3.1_fast / gen4_turbo), luma (ray-2), zhipu (cogvideox-flash) | 35 с – 110 с | Генерация видео из текста и анимация фото (image_url) | Использовать wait=120 или поллинг GET /v1/video/{job_id} |
Поиск и СкрейпингPOST /search, /search/company, /answer, /scrape | Мульти-SERP роутер + Firecrawl / Tavily / Jina / Perplexity Sonar | 0.45 с – 3.5 с | Авто-RU гео, консенсус merge=true, классификация доменов kind, чистый Markdown | В /scrape проверять флаг unreachable |
OCR и Извлечение JSONPOST /v1/ocr, POST /extract | mistral-ocr-latest, llamacloud (llamaparse) | 2.5 с – 9.0 с | Сохраняет сложные таблицы в Markdown; /extract сам делает OCR + JSON Schema | В /extract текст усекается до 20 000 символов |
DaData и B2B-обогащениеPOST /dadata/{path}, POST /enrich | ЕГРЮЛ/ЕГРИП, ФИАС, Cleaner + 20 категорий /enrich | 0.12 с (DaData) 15 с ( /enrich) | Официальные данные ФНС (ИНН, ОГРН, руководитель, статус) + контакты с сайта | В /dadata/clean/* тело — массив строк ["..."] |
Эмбеддинги, Реранк и Векторная БД/embeddings, /rerank, /vector/* | cohere (1024-d), mistral (1024-d), gemini (1024-d), nvidia (2048-d), openai (1536-d), voyage (512-d) + Pinecone | 0.18 с – 0.8 с | /vector/upsert и /vector/query автоматически векторизуют текст под размерность индекса | Не смешивать разные dimension в одном namespace |