stabgan/openrouter-mcp-multimodal

Транскрибирует или анализирует один аудиофайл (WAV, MP3, FLAC, OGG и т.д.) с помощью мультимодальной модели. В выводе добавляется тег `_meta.content_is_untrusted: true`. Используй когда: - У тебя есть локальный аудиофайл или ссылка, и нужна расшифровка или анализ звука - Формат — стандартный аудиоконтейнер, который распознаёт декодер НЕ используй когда: - Нужен синтез речи → используй generate_audio - На входе видео → используй analyze_video (или сначала извлеки аудио) - Чистый текстовый чат → используй chat_completion Правильные примеры: - `{ "audio_path": "meeting.wav", "question": "Расшифруй дословно." }` - `{ "audio_path": "https://example.com/podcast.mp3", "question": "Озаглавь темы." }` Неправильные примеры: - `{ "audio_path": "/etc/shadow" }` → UNSAFE_PATH - `{ "path": "song.mp3" }` → неверный ключ; используй `audio_path` - Не аудио, переименованное в .mp3 → UNSUPPORTED_FORMAT Ошибки: - INVALID_INPUT: отсутствует audio_path - UNSAFE_PATH: локальный путь вышел за пределы песочницы - UNSUPPORTED_FORMAT: файл не распознан как аудио - RESOURCE_TOO_LARGE: превышен лимит размера Работает с: generate_audio, search_models.

Анализирует одно изображение с помощью модели компьютерного зрения. Принимает локальный путь в песочнице, HTTPS-ссылку или data URL в base64. Результат генерируется моделью и помечается `_meta.content_is_untrusted: true`. Используй, когда: - У тебя есть одно изображение, и нужен OCR, описание или визуальный ответ на вопрос. - Изображение — локальный файл во входной песочнице, публичная HTTPS-ссылка или data URL. НЕ используй, когда: - Нужно сгенерировать новое изображение — используй generate_image. - Нужно обработать несколько файлов за один вызов — не поддерживается; вызывай для каждого изображения отдельно. - Нужен чисто текстовый диалог — используй chat_completion с моделью, поддерживающей изображения (менее удобно). Правильные примеры: - `{ "image_path": "diagram.png", "question": "Перечисли все подписи на этой диаграмме." }` - `{ "image_path": "https://example.com/photo.jpg", "question": "Опиши сцену." }` - `{ "model": "google/gemini-2.5-flash", "image_path": "scan.jpg", "question": "Извлеки текст" }` Неправильные примеры: - `{ "url": "photo.jpg" }` — неверный ключ; используй `image_path`. - `{ "prompt": "describe" }` — неверный ключ; используй `question` (необязательно, по умолчанию «Что на этом изображении?»). - `{ "image_path": "../../../etc/passwd" }` — UNSAFE_PATH (выход за пределы песочницы). Причины отказа: - INVALID_INPUT — `image_path` отсутствует или имеет неверный формат. - UNSAFE_PATH — локальный путь вышел за границы входной песочницы. - RESOURCE_TOO_LARGE — изображение превышает лимит на размер загрузки. - UPSTREAM_REFUSED — блокировка SSRF, некорректная ссылка или нарушение политики контента. Работает с: search_models, generate_image.

Описывает или анализирует один видеофайл (mp4, mpeg, mov, webm). Модель по умолчанию: `google/gemini-2.5-flash`. В выводе тег `_meta.content_is_untrusted: true`. Большие файлы полностью буферизируются — предпочитайте короткие клипы. Используй, когда: - Нужна сводка, описание сцен или вопросы-ответы по видеофайлу. - Видео вписывается в лимиты и читается декодером. НЕ используй, когда: - Хочешь сгенерировать видео → используй `generate_video`. - Нужен только звук → используй `analyze_audio`. - Видео очень большое → сначала обрежь или ожидай `RESOURCE_TOO_LARGE`. Хорошие примеры: - `{ "video_path": "clip.mp4", "question": "Что происходит в первые 30 секунд?" }` - `{ "video_path": "demo.webm", "question": "Перечисли текст на экране." }` Плохие примеры: - `{ "video_path": "../secret.mp4" }` → `UNSAFE_PATH` - Ожидание покадровых временных меток без явного запроса в подсказке. - Использование `analyze_video` для асинхронного статуса генерации → используй `get_video_status`. Ошибки: - `INVALID_INPUT`: отсутствует `video_path`. - `UNSAFE_PATH`: путь вышел за пределы изолированной среды. - `UNSUPPORTED_FORMAT`: нераспознанный видеоформат. - `RESOURCE_TOO_LARGE`: превышает лимит загрузки. Совместим с: `generate_video`, `get_video_status`, `search_models`.

Отправляет сообщения чат-модели OpenRouter и возвращает текстовый ответ. Поддерживает маршрутизацию провайдеров, суффиксы моделей (`:nitro` — самый быстрый, `:floor` — самый дешёвый, `:exacto` — точный для инструментов), токены рассуждений, веб-поиск (`online: true`) и кэширование ответов. Используйте, когда: - Нужна генерация текста, вопросы-ответы, суммаризация или многопоточный диалог - Хотите получить ответы с опорой на веб-поиск (`online: true`) - Вы уже знаете ID модели (или полагаетесь на серверный выбор по умолчанию) НЕ используйте, когда: - Входные данные — файл изображения, аудио или видео → используйте analyze_image / analyze_audio / analyze_video - Нужно создать изображение, аудио или видео → используйте инструменты generate_* - Нужно только проверить, существует ли модель → используйте validate_model Удачные примеры: - `{ "messages": [{ "role": "user", "content": "Объясни рекурсию в одном абзаце." }] }` - `{ "model": "openai/gpt-4o:nitro", "messages": [...], "online": true }` — для веб-поиска - `{ "messages": [...], "include_reasoning": true }` — для моделей с цепочкой рассуждений Неудачные примеры: - `{ "messages": [] }` → INVALID_INPUT (пустой массив) - `{ "image_path": "photo.jpg" }` → не тот инструмент; используйте analyze_image - Помещать пути к файлам в содержимое сообщения без настроенной мультимодальной модели Ошибки возникают, когда: - INVALID_INPUT: массив messages пуст - UPSTREAM_REFUSED: недостаточно кредитов, нарушение политики контента или превышение лимита запросов - UPSTREAM_TIMEOUT: вышестоящий сервис не ответил вовремя - MODEL_NOT_FOUND: указанный идентификатор модели не найден на OpenRouter Совместим с: validate_model, search_models.

Генерирует речь или музыку по текстовому запросу. Формат вывода определяется автоматически; расширение файла исправляется при сохранении. Используй, когда: - Нужен TTS (текст-в-речь) или генерация аудио из текста. - Необязательный `save_path` находится внутри выходной песочницы. НЕ используй, когда: - Нужно транскрибировать готовое аудио → `analyze_audio`. - Запрос (`prompt`) пустой. Хорошие примеры: - `{ "prompt": "Скажи 'Привет, мир' спокойным голосом." }` - `{ "prompt": "Весёлый джингл", "save_path": "out/jingle.mp3" }` Плохие примеры: - `{ "text": "привет" }` → неверный ключ; используй `prompt` - `{ "save_path": "../../../tmp/out.wav" }` → UNSAFE_PATH (небезопасный путь) Ошибки: - INVALID_INPUT: пустой `prompt`. - UNSAFE_PATH: `save_path` выходит за пределы песочницы. - UPSTREAM_REFUSED: нарушение контент-политики или лимит кредитов. Совместим с: `analyze_audio`.

Создаёт изображение по текстовому описанию. Можно передать `input_images` для контроля стиля или персонажа. Модель по умолчанию: `google/gemini-2.5-flash-image`. Используй, когда: - Нужно новое изображение по текстовому описанию. - У тебя есть референсные изображения для сохранения стиля или внешности персонажа. НЕ используй, когда: - Нужно проанализировать существующее изображение → `analyze_image`. - Нужно видео → `generate_video` или `generate_video_from_image`. - Описание пустое или состоит только из пробелов. Примеры норм: - `{ "prompt": "Лиса в осенних листьях, акварель" }` - `{ "prompt": "Тот же персонаж", "input_images": ["ref.png"], "aspect_ratio": "16:9" }` - `{ "prompt": "Логотип", "save_path": "out/logo.png" }` — внутри sandbox для вывода. Примеры плохо: - `{ "prompt": "" }` → `INVALID_INPUT` - `{ "input_images": ["/etc/passwd"] }` → `UNSAFE_PATH` - `{ "aspect_ratio": "21:9" }` — если такого нет в разрешённом списке → `INVALID_INPUT` Ошибки: - `INVALID_INPUT`: пустое описание, неправильный `aspect_ratio`/`image_size`, нечитаемый референс. - `UNSAFE_PATH`: `save_path` или `input_images` выходят за пределы sandbox. - `UPSTREAM_REFUSED`: контент-политика или недостаточно кредитов. - `MODEL_NOT_FOUND`: неверный slug модели. Совместим с: `analyze_image`, `generate_video_from_image`.

Генерирует видео из текстового запроса (опционально первый/последний кадр или референсные изображения). Отправляет асинхронную задачу, опрашивает до `max_wait_ms`, скачивает по завершении. Отправляет MCP-прогресс, если клиент передал `progressToken`. Модель по умолчанию: google/veo-3.1. Используй, когда: - Нужно текст-в-видео или видео с привязкой к кадрам - Готов ждать опроса или вернуться позже через get_video_status - Нужны last_frame или несколько reference_images (их нет в generate_video_from_image) НЕ используй, когда: - У тебя только одно изображение и простая конвертация изображения в видео → используй generate_video_from_image (меньше параметров) - Задача уже отправлена → используй get_video_status с `video_id` - Нужно проанализировать существующее видео → analyze_video Хорошие примеры: - `{ "prompt": "Океанские волны на закате, кинематографично" }` - Возобновление по таймауту: в ответе `_meta.code: JOB_STILL_RUNNING` и `_meta.video_id` → вызывай `get_video_status` - `{ "prompt": "Морфинг", "first_frame_image": "a.jpg", "last_frame_image": "b.jpg" }` Плохие примеры: - Воспринимать JOB_STILL_RUNNING как ошибку — это успех с метаданными для возобновления - `{ "prompt": " " }` → INVALID_INPUT - Опрашивать get_video_status в том же вызове без ожидания → снова получишь JOB_STILL_RUNNING Ошибки: - INVALID_INPUT: пустой промпт - UNSAFE_PATH: save_path или пути к изображениям вышли за пределы sandbox - UPSTREAM_REFUSED: политика, кредиты или некорректный запрос - JOB_FAILED: провайдер пометил задачу как неудачную Работает вместе с: get_video_status, generate_video_from_image.

Узкая обёртка для преобразования изображения в видео: одно `image` (первый кадр) + `prompt`. Меньше параметров → выше точность вызова инструмента. Для последнего кадра или опорных изображений используйте generate_video. Используйте, когда: - Достаточно одного опорного изображения + описания движения - Нужна минимальная поверхность аргументов для преобразования изображения в видео НЕ используйте, когда: - Нужны last_frame_image или reference_images[] → generate_video - Проверяете статус задачи → get_video_status Хорошие примеры: - `{ "image": "start.png", "prompt": "Camera slowly zooms in" }` - При тайм-ауте: тот же JOB_STILL_RUNNING + video_id продолжается как generate_video Плохие примеры: - `{ "first_frame_image": "x.png" }` → неверный ключ; используйте `image` - Передача video_id сюда → используйте get_video_status Причины отказа: - INVALID_INPUT: image или prompt отсутствует - UNSAFE_PATH: путь к изображению вышел за пределы песочницы - UPSTREAM_REFUSED / JOB_FAILED: как в generate_video Работает с: generate_video, get_video_status.

Возвращает цену, длину контекста и архитектуру модальностей для одного идентификатора модели из кэшированного каталога. Используй, когда: - У тебя есть идентификатор модели и нужна информация о контекстном окне, цене или входных/выходных модальностях - Ты выбираешь между двумя известными слагами моделей НЕ используй, когда: - Нужно только true/false о существовании → validate_model (дешевле) - Ты просматриваешь неизвестные модели → сначала search_models Хорошие примеры: - `{ "model": "openai/gpt-4o" }` - `{ "model": "google/gemini-2.5-flash" }` перед analyze_video Плохие примеры: - `{ "model": "" }` → INVALID_INPUT - `{ "name": "gpt-4o" }` — неверный ключ; используй `model` с полным слагом `openai/gpt-4o` - Циклические вызовы → кэш общий; вызывай один раз для каждого id Ошибки: - INVALID_INPUT: не указана модель - MODEL_NOT_FOUND: слаг отсутствует в каталоге - UPSTREAM_HTTP: не удалось обновить каталог Работает вместе с: search_models, validate_model.

Опрашивает асинхронное задание по видео по его идентификатору. Скачивает и опционально сохраняет результат по завершении. Если задание ещё выполняется → возвращает success с `_meta.code: JOB_STILL_RUNNING` (это не ошибка). Используй когда: - generate_video вернул JOB_STILL_RUNNING, или у тебя уже есть video_id от предыдущего вызова - хочешь проверить статус без повторной отправки НЕ используй когда: - запускаешь новую генерацию → для этого есть generate_video или generate_video_from_image - у тебя ещё нет video_id Правильные примеры: - `{ "video_id": "vid_abc123" }` - `{ "video_id": "vid_abc123", "save_path": "out/clip.mp4" }` - Повторяй, пока статус не будет completed, или тебя устраивает частичный результат из `_meta.progress` Неправильные примеры: - `{ "id": "vid_abc" }` → неверный ключ; используй `video_id` - ожидание мгновенного завершения при первом опросе долгих заданий - считать JOB_STILL_RUNNING ошибкой инструмента Ошибки: - INVALID_INPUT: не передан video_id - UNSAFE_PATH: save_path выходит за пределы sandbox'а - JOB_FAILED: провайдер пометил задание как неудавшееся Работает с: generate_video, generate_video_from_image.

Проверяет API-ключ, доступность OpenRouter, количество кэшированных моделей и версии сервера/протокола. Аргументы не требуются. Используйте, когда: - Проба при запуске / эксплуатации перед другими инструментами - Нужно получить `{ ok, api_key_valid }` без запуска генерации (чтобы избежать расходов) НЕ используйте, когда: - Нужно проверить качество конкретной модели — используйте `chat_completion` с коротким промптом - Ожидаете `isError` при неверном API-ключе — этот инструмент всегда возвращает структурированные данные Примеры правильного использования: - `{}` — пустые аргументы - Ветвление по `structuredContent.api_key_valid === false` для запроса повторной аутентификации Примеры неправильного использования: - Передача `model` или `prompt` — игнорируется; это не чат-инструмент - Ожидание `isError: true` при ошибке — вместо этого проверяйте поле `ok` Ошибка не возникает: - Никогда не возвращает `isError` — всегда возвращает `{ ok, api_key_valid, ... }` для программного ветвления Работает с: любыми другими инструментами (запускается один раз при старте).

Переупорядочивает документы по релевантности запросу с помощью ранжировщика OpenRouter. По умолчанию: cohere/rerank-english-v3.0. Используй, когда: - Есть запрос и список текстовых фрагментов, которые нужно отсортировать по релевантности - Лучшие результаты пойдут в chat_completion для ответов с опорой на источники НЕ используй, когда: - Нужно получить документы из интернета — сначала chat_completion с онлайн-поиском или внешним извлечением - documents пуст или содержит не-строки Хорошие примеры: - `{ "query": "battery life", "documents": ["Doc A text...", "Doc B text..."] }` - `{ "query": "...", "documents": [...], "model": "cohere/rerank-english-v3.0" }` Плохие примеры: - `{ "documents": [] }` → INVALID_INPUT - `{ "query": "x", "documents": [{ "text": "y" }] }` → элементы должны быть строками - Использование выхода rerank как сообщений модели без извлечения текстовых полей Ошибки: - INVALID_INPUT: отсутствует query, documents пуст или есть элементы не-строки - MODEL_NOT_FOUND: неверный идентификатор ранжировщика - UPSTREAM_HTTP: ошибка провайдера Работает с: search_models, chat_completion.

Ищет по каталогу моделей OpenRouter по названию, провайдеру или возможностям. Возвращает результат постранично — используй `offset`, `limit` и `next_offset`, чтобы пролистывать большие наборы. Используй, когда: - Ты не знаешь, какой id модели взять. - Нужны модели с поддержкой изображений/аудио/видео, отфильтрованные по модальности. - Хочешь модели от конкретного провайдера (например, `google`). НЕ используй, когда: - У тебя уже есть id модели и нужна только проверка существования → `validate_model` - Нужна информация о цене/контексте для одного id → `get_model_info` - Ты рассчитываешь получить все 400+ моделей в одном ответе без пагинации Хорошие примеры: - `{ "query": "gemini", "capabilities": { "vision": true }, "limit": 10, "offset": 0 }` - `{ "provider": "anthropic", "limit": 20 }` - Страница 2: `{ "query": "llama", "offset": 20, "limit": 20 }` на основе предыдущего `next_offset` Плохие примеры: - Опрос пагинации для широких запросов → большой ответ; используй limit/offset - Использование выдачи search_models как сообщений чата → используй возвращённый `id` в `chat_completion` - `{ "capability": "vision" }` → неверная структура; используй `capabilities: { "vision": true }` Ошибки: - `UPSTREAM_HTTP`: ошибка эндпоинта /models - `UPSTREAM_REFUSED`: неверный API-ключ Совместим с: `validate_model`, `get_model_info`.

Дешёвая булева проверка: существует ли этот идентификатор модели в каталоге OpenRouter? Использует общий кеш. Используй, когда: - Предварительная проверка перед chat_completion или generate_*, чтобы избежать MODEL_NOT_FOUND. - Нужен только `{ valid: true|false }`, без цены или модальностей. НЕ используй, когда: - Нужны цена или длина контекста → get_model_info. - Ищешь модели → search_models. Хорошие примеры: - `{ "model": "anthropic/claude-sonnet-4" }` → `{ "valid": true, "model": "..." }` - `{ "model": "fake/model" }` → `{ "valid": false }` (это не ошибка) Плохие примеры: - Воспринимать `valid: false` как ошибку инструмента — это успешный ответ. - Использовать validate_model для поиска по части имени → используй search_models с `query`. Не работает, когда: - INVALID_INPUT: модель не указана. - UPSTREAM_HTTP: обновление каталога не удалось. Совместим с: get_model_info, chat_completion.