stabgan/openrouter-mcp-multimodal

Транскрибирует или анализирует один аудиофайл (WAV, MP3, FLAC, OGG и т. д.) с помощью мультимодальной модели. Результат помечается тегом _meta.content_is_untrusted: true. Используйте, когда: - У вас есть локальный аудиофайл или URL, и нужна транскрипция или анализ аудио - Формат - распространённый аудиоконтейнер, который распознаёт декодер НЕ используйте, когда: - Нужен синтез речи (text-to-speech) → используйте text_to_speech (отдельный инструмент, быстрее) или generate_audio (чат-маршрут, музыка/звуковые эффекты) - Нужна только транскрипция без вопросов и ответов → используйте speech_to_text - На входе видео → используйте analyze_video (или сначала извлеките аудио) Удачные примеры: - { "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.

Анализирует одно изображение с помощью vision-модели. Принимает локальный путь в песочнице ввода, https URL или base64 data URL. Результат создаётся моделью и помечается тегом _meta.content_is_untrusted: true. Используйте, когда: - У вас есть одно изображение, и нужны OCR, генерация подписей или визуальные вопросы и ответы - Изображение: локальный файл в песочнице ввода, публичный https URL или data URL НЕ используйте, когда: - Нужно сгенерировать новое изображение → используйте generate_image или generate_image_dedicated - Нужен пакетный анализ нескольких файлов одним вызовом → не поддерживается; вызывайте по одному разу на каждое изображение - Нужен многоходовой визуальный чат с несколькими изображениями → используйте chat_completion с vision-моделью (analyze_image работает только с одним изображением) Хорошие примеры: - { "image_path": "diagram.png", "question": "Перечисли все надписи на этой диаграмме." } - { "image_path": "https://example.com/photo.jpg", "question": "Опиши сцену." } - { "image_path": "scan.jpg", "question": "Извлеки текст", "model": "google/gemini-2.5-flash" } (необязательное переопределение модели) Плохие примеры: - { "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, некорректный URL или политика контента Работает с: 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 самая дешёвая, :free бесплатная, :online веб-поиск, :exacto точность инструментов), токены рассуждений, веб-поиск (online: true) и кэширование ответов. Используйте, когда: - Вам нужна генерация текста, Q&A, суммаризация или многоходовой диалог - Вы хотите получить ответы с учётом веб-информации (online: true) - Вы уже знаете идентификатор модели (или полагаетесь на серверный вариант по умолчанию) Не используйте, когда: - На входе один файл изображения/аудио/видео → используйте analyze_image / analyze_audio / analyze_video (специализированные обёртки) - Вам нужно создать изображение, аудио или видео → используйте инструменты generate_* / text_to_speech - Вам нужно только проверить, существует ли модель → используйте validate_model Хорошие примеры: - { "messages": [{ "role": "user", "content": "Explain recursion in one paragraph." }] } - { "model": "openai/gpt-4o:nitro", "messages": [...], "online": true } для веб-поиска - { "messages": [...], "include_reasoning": true } для моделей chain-of-thought Плохие примеры: - { "messages": [] } → INVALID_INPUT (пустой массив) - { "image_path": "photo.jpg" } → не тот инструмент; используйте analyze_image - Передача путей к файлам внутри содержимого сообщения без настроенной vision-модели Ошибки возникают, когда: - INVALID_INPUT: массив messages пуст - UPSTREAM_REFUSED: недостаточно кредитов, сработала политика контента или превышен лимит запросов - UPSTREAM_TIMEOUT: вышестоящий сервис не ответил вовремя - MODEL_NOT_FOUND: model slug не существует в OpenRouter Работает с: validate_model, search_models.

Генерирует речь или музыку через chat completions (маршрут modalities). Форматы: wav, mp3, flac, opus, pcm16. Модель по умолчанию: openai/gpt-audio, голос alloy. Для отдельного TTS со скоростью и инструкциями используйте text_to_speech. Используйте, когда: - Нужна музыка, звуковые эффекты или выразительная речь через чат-маршрут - Нужен вывод pcm16/wav из семейства gpt-audio НЕ используйте, когда: - Нужен быстрый отдельный TTS со скоростью и инструкциями → text_to_speech - Нужно транскрибировать существующее аудио → speech_to_text или analyze_audio - Промпт пустой Хорошие примеры: - { "prompt": "Say hello world in a calm voice." } - { "prompt": "Upbeat jingle", "save_path": "out/jingle.mp3" } Плохие примеры: - { "text": "hello" } → неверный ключ; используйте prompt - { "save_path": "../../../tmp/out.wav" } → UNSAFE_PATH Ошибки при: - INVALID_INPUT: промпт пустой - UNSAFE_PATH: save_path вышел за пределы песочницы - UPSTREAM_REFUSED: контентная политика или кредиты Работает с: analyze_audio.

Генерирует изображение через chat completions (маршрут modalities). Необязательные input_images для стиля и идентичности. Модель по умолчанию: google/gemini-2.5-flash-image. Для управления разрешением, качеством и форматом или для более новых моделей Image API используйте generate_image_dedicated. Используйте, когда: - Нужно новое изображение по текстовому запросу через маршрут chat-completions - Есть референсные изображения, чтобы сохранить стиль или объект (input_images) - Нужно простое преобразование текста в изображение без специальных настроек API НЕ используйте, когда: - Нужны уровни разрешения, качество, output_format или модели только Image API → generate_image_dedicated - Нужно проанализировать существующее изображение → analyze_image - Нужно видео → generate_video или generate_video_from_image - Промпт пустой или содержит только пробелы Хорошие примеры: - { "prompt": "A watercolor fox in autumn leaves" } - { "prompt": "Same character", "input_images": ["ref.png"], "aspect_ratio": "16:9" } - { "prompt": "Logo", "save_path": "out/logo.png" } внутри выходной песочницы Плохие примеры: - { "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 вышли за пределы песочницы - UPSTREAM_REFUSED: нарушение политики контента или недостаточно кредитов - MODEL_NOT_FOUND: неверный slug модели Работает с: analyze_image, generate_video_from_image.

Генерирует изображения через отдельный Image API OpenRouter (POST /api/v1/images). Поддерживает нормализованные уровни разрешения, уровни качества, выбор выходного формата и референсные изображения. Новые модели изображений добавляются только в этот эндпоинт. Модель по умолчанию: google/gemini-2.5-flash-image. Используйте, когда: - Нужна генерация изображений с точным контролем разрешения, качества и формата - Хотите использовать новые модели изображений, доступные только в отдельном API - Нужно преобразование изображение-в-изображение с input_references Не используйте, когда: - Простой текстовый запрос на генерацию изображения без контроля формата или разрешения → generate_image (меньше параметров) - Нужно проанализировать существующее изображение → analyze_image - Нужно видео → generate_video или generate_video_from_image - Поле prompt пустое или состоит только из пробелов Примеры правильного использования: - { "prompt": "A watercolor fox", "resolution": "2K", "quality": "high" } - { "prompt": "Product shot", "input_references": ["product.jpg"], "aspect_ratio": "16:9" } - { "prompt": "Logo", "output_format": "svg", "save_path": "out/logo.svg" } Примеры некорректного использования: - { "prompt": "" } → INVALID_INPUT - { "resolution": "8K" } → значение не входит в допустимый enum - { "quality": "ultra" } → значение не входит в допустимый enum Возвращает ошибку в случаях: - INVALID_INPUT: пустой prompt, недопустимые resolution/quality/output_format - UNSAFE_PATH: save_path или input_references вышли за пределы песочницы - 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.

Проверяет статус асинхронной задачи чат-генерации, запущенной с помощью start_chat_completion. Возвращает полный ответ, когда задача завершена, или текущий статус (running/failed) в противном случае. Используйте, когда: - Вы ранее вызывали start_chat_completion и нужно проверить, завершилась ли задача - Нужно опросить результат долго выполняющейся модели рассуждений НЕ используйте, когда: - Вы ещё не запускали задачу → сначала вызовите start_chat_completion - Вы хотите запустить новую генерацию Хорошие примеры: - { "job_id": "chat_20260806_001" } Плохие примеры: - { "job_id": "" } → INVALID_INPUT - { "job_id": "nonexistent" } → задача не найдена Выдаёт ошибку, когда: - INVALID_INPUT: пустой job_id - JOB_FAILED: фоновая генерация столкнулась с ошибкой - Задача не найдена: неверный job_id или задача из предыдущей сессии Работает с: start_chat_completion, chat_completion.

Возвращает цену, длину контекста и архитектуру модальностей для одного идентификатора модели из кэшированного каталога. Используй, когда: - У тебя есть идентификатор модели и нужна информация о контекстном окне, цене или входных/выходных модальностях - Ты выбираешь между двумя известными слагами моделей НЕ используй, когда: - Нужно только 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.

Транскрибирует аудио через выделенную конечную точку STT OpenRouter (POST /api/v1/audio/transcriptions). Быстрее и дешевле, чем chat completions, для чистой транскрипции. Модели: Whisper-1, GPT-4o Transcribe, Voxtral. Используйте, когда: - Нужна быстрая транскрипция аудиофайлов - Нужно только распознавание речи без анализа и Q&A - Нужен структурированный вывод (SRT, VTT, verbose JSON) НЕ используйте, когда: - Нужно задавать вопросы об аудио → analyze_audio - Нужен анализ музыки или определение звуков → analyze_audio - Нужен TTS → text_to_speech или generate_audio Хорошие примеры: - { "audio_path": "recording.mp3" } - { "audio_path": "meeting.wav", "language": "en", "response_format": "srt" } - { "audio_path": "https://example.com/audio.mp3", "model": "openai/gpt-4o-transcribe" } Плохие примеры: - { "audio_path": "" } → INVALID_INPUT - { "path": "audio.mp3" } → неправильный ключ; используйте audio_path - { "audio_path": "/etc/shadow" } → UNSAFE_PATH Завершается ошибкой, когда: - INVALID_INPUT: пустой audio_path, неверный response_format, нечитаемый файл - UNSAFE_PATH: audio_path вышел за пределы песочницы - UPSTREAM_REFUSED: неподдерживаемый формат или закончились кредиты Работает с: text_to_speech, analyze_audio.

Запускает chat completion как асинхронную фоновую задачу. Сразу возвращает job_id, не дожидаясь ответа модели. Используйте get_chat_completion_status, чтобы опрашивать результаты. Рассчитан на reasoning-модели и любые запросы, которые могут превысить тайм-аут MCP (~60 с). Используйте, когда: - Используете reasoning-модель, которая может отвечать больше 60 секунд (DeepSeek R1, Claude Opus и т. п.) - Подключены через удалённый MCP-мост с короткими тайм-аутами - Хотите отправить completion и забыть о нём, а позже проверить результат НЕ используйте, когда: - Быстрые модели отвечают за секунды → используйте chat_completion напрямую - Нужен потоковый вывод → используйте chat_completion - Массив messages пуст Хорошие примеры: - { "messages": [{ "role": "user", "content": "Prove the Riemann hypothesis" }], "model": "deepseek/r1" } - { "messages": [...], "include_reasoning": true } для длинной цепочки рассуждений Плохие примеры: - { "messages": [] } → INVALID_INPUT - Не используйте для простых запросов вроде «hello world» (лишняя нагрузка) Ошибки возникают, когда: - INVALID_INPUT: пустой массив messages - Задача может завершиться ошибкой в фоне, если модель выдаст ошибку или закончатся кредиты Работает с: get_chat_completion_status, chat_completion.

Преобразует текст в речь через выделенный TTS-endpoint OpenRouter (POST /api/v1/audio/speech). Для чистого TTS быстрее и дешевле, чем chat completions. Модели: OpenAI GPT-4o Mini TTS, Google Gemini Flash TTS, Mistral Voxtral. Используйте, когда: - Нужен TTS с выбором конкретного голоса - Хотите быстрый выделенный TTS без обвязки чата - Нужен конкретный аудиоформат (mp3, opus, wav и т. д.) Не используйте, когда: - Нужно сгенерировать музыку или звуковые эффекты → generate_audio - Нужно расшифровать аудио → speech_to_text или analyze_audio - Входной текст пуст Хорошие примеры: - { "input": "Hello, welcome to our app!" } - { "input": "...", "voice": "nova", "response_format": "mp3", "save_path": "out/welcome.mp3" } - { "input": "...", "instructions": "speak slowly and clearly", "speed": 0.8 } Плохие примеры: - { "input": "" } → INVALID_INPUT - { "prompt": "text" } → неверный ключ; используйте input - { "response_format": "mp4" } → недопустимый аудиоформат Не работает, когда: - INVALID_INPUT: пустой input, недопустимый response_format - UNSAFE_PATH: save_path вышел за пределы sandbox - UPSTREAM_REFUSED: политика контента или закончились кредиты Работает с: speech_to_text, analyze_audio.

Дешёвая булева проверка: существует ли этот идентификатор модели в каталоге 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.