Единый API для всех модальностей: OpenRouter

Представьте себе типичный сценарий разработки современного AI-приложения. Вы создаете приложение, которое не просто отвечает на вопросы в чате, но и генерирует иллюстрации для товаров, ищет информацию в базе знаний с помощью семантического поиска, а также преобразует голосовые заметки пользователей в текст. На первый взгляд, задача кажется стандартной. Однако, если вы решите реализовать это «по классике», используя прямые интеграции с провайдерами, вы столкнетесь с настоящим адом инженерии. Вам придется подключать четыре разных SDK, настраивать четыре отдельные системы аутентификации, управлять четырьмя счетами в разных платежных системах и писать код для обработки уникальных форматов ошибок и таймаутов для каждого сервиса.

Именно эту боль пытается решить OpenRouter, предлагая концепцию «одной API для всех модальностей». Их подход заключается в том, чтобы скрыть сложность взаимодействия с десятками провайдеров (от OpenAI до Anthropic, Google и других) за единым интерфейсом, совместимым с OpenAI. В этой статье мы подробно разберем, как работает эта архитектура, какие эндпоинты используются для разных типов данных, как настроить отказоустойчивость и где кроются подводные камни, о которых молчат в документации.

01Философия единого входа: почему это важно

Основная ценность OpenRouter заключается в консолидации. Вместо того чтобы иметь дело с разрозненными API, вы получаете один базовый URL: https://openrouter.ai/api/v1. Это не просто удобство для разработчика, это фундаментальное изменение в том, как мы строим AI-инфраструктуру. Когда вы устанавливаете этот базовый URL один раз, вся дальнейшая работа сводится к изменению строки модели и типа контента в запросе.

Каталог OpenRouter включает более 400 моделей от более чем 70 провайдеров. Это означает, что вы можете переключаться между моделями для генерации текста, создания изображений или вычисления векторных представлений (эмбеддингов), не меняя ни строчки кода в части аутентификации или сетевых настроек. Те же механизмы маршрутизации, которые защищают ваш чат-бот от сбоев, работают и для запросов на генерацию изображений или вычисление эмбеддингов. Это снижает технический долг и упрощает масштабирование.

02Карта эндпоинтов: где что отправлять

Одной из самых запутанных частей работы с AI-моделями является понимание того, какой HTTP-метод и какой путь (endpoint) использовать для каждой модальности. В OpenRouter эта логика строго структурирована. Большинство входных модальностей (текст, изображения для анализа, PDF, аудио, видео) используют стандартный эндпоинт /chat/completions, различаясь лишь типом контента в массиве сообщений. Однако для задач генерации и специфической обработки данных выделены отдельные эндпоинты.

Давайте разберем полную карту эндпоинтов, чтобы вы четко понимали, куда отправлять запросы:

Текст / Чат: POST /api/v1/chat/completions. Стандартный массив сообщений.
Входные изображения (Vision): POST /api/v1/chat/completions. Используется поле image_url в контенте.
PDF-файлы: POST /api/v1/chat/completions. Используется поле file.
Входное аудио: POST /api/v1/chat/completions. Используется поле input_audio.
Входное видео: POST /api/v1/chat/completions. Используется поле video_url.
Генерация изображений: POST /api/v1/images. На вход подается промпт, на выходе — изображения в формате base64.
Генерация видео: POST /api/v1/videos. Асинхронный процесс: вы отправляете промпт, получаете ID задачи и опрашиваете статус.
Текст в речь (TTS): POST /api/v1/audio/speech. На вход текст, на выходе байты MP3 или PCM.
Транскрипция (STT): POST /api/v1/audio/transcriptions. На вход base64 аудио, на выходе JSON с текстом и статистикой.
Эмбеддинги: POST /api/v1/embeddings. На вход текст или текст+изображение, на выходе векторы.

Пять модальностей используют эндпоинт /chat/completions, так как их форма запроса схожа с обычным чатом. Остальные пять имеют выделенные эндпоинты, потому что их логика работы отличается: генерация изображений требует специфических параметров (разрешение, соотношение сторон), генерация видео работает асинхронно через polling, а эмбеддинги возвращают векторы, а не текстовые завершения.

Таблица соответствия модальностей и эндпоинтов

03Когда какую модальность использовать?

Понимание разницы между генерацией и пониманием (understanding) критически важно. Даже в рамках одного типа медиа, например, изображений, задачи кардинально различаются. Давайте разберем практические сценарии для каждой модальности.

Изображения: генерация против анализа

Если вам нужно создать новую картинку, иллюстрацию или макет продукта, используйте генерацию изображений через эндпоинт /api/v1/images. Вы передаете текстовый промпт и, опционально, референсные изображения для работы в стиле image-to-image. Результатом будут изображения в формате base64. С другой стороны, если у вас уже есть изображение, которое нужно проанализировать (распознать текст, описать содержимое, обнаружить объекты), вы отправляете URL изображения через поле image_url в запросе к /chat/completions. Модель вернет текстовое описание или ответ на ваш вопрос.

Единый API для всех модальностей: как OpenRouter упрощает работу с AI

Видео: создание против анализа

Генерация видео — это асинхронный процесс. Вы отправляете запрос на /api/v1/videos с промптом, параметрами разрешения и длительности, и получаете ID задачи. Затем вам нужно периодически опрашивать статус задачи, пока видео не будет готово. Для анализа видео (распознавание действий, детекция объектов) вы используете эндпоинт /chat/completions, передавая URL видео в поле video_url. Это позволяет моделям, поддерживающим видео, «смотреть» контент и давать текстовые ответы.

Аудио: синтез против анализа

Для преобразования текста в речь (Text-to-Speech) используйте /api/v1/audio/speech. Этот эндпоинт совместим с OpenAI Audio API, поэтому вы можете использовать стандартные клиентские библиотеки OpenAI. На выходе вы получаете байты аудиофайла (MP3 или PCM). Для анализа аудио (например, определение тональности или извлечение текста из голосового сообщения) используйте /chat/completions с полем input_audio. Это позволяет моделям обрабатывать аудио как часть контекста диалога.

Эмбеддинги: поиск и сходство

Эмбеддинги не генерируют контент, они создают векторные представления данных. Они необходимы для задач RAG (Retrieval-Augmented Generation), семантического поиска, рекомендаций, кластеризации, обнаружения дубликатов и аномалий. Эндпоинт /api/v1/embeddings позволяет отправлять батчи текстов, а некоторые модели (например, nvidia/llama-nemotron-embed-vl-1b-v2) могут принимать одновременно текст и изображение, создавая единый вектор, который объединяет оба типа данных. Это мощно для систем, где нужно искать текстовые документы по картинкам или наоборот.

Транскрипция: речь в текст

Для преобразования голосовых команд, записей встреч или субтитров в текст используйте /api/v1/audio/transcriptions. Вы отправляете аудио в формате base64, а получаете JSON с расшифрованным текстом и метаданными об использовании. Это идеальный выбор для задач, где нужен именно текст, а не анализ тональности или контекста.

💡

Совет по тестированию. Вы можете тестировать мультимодальные входы без оплаты. OpenRouter предлагает бесплатный тариф без привязки кредитной карты. Свободные модели работают с низкими дневными лимитами, которых достаточно, чтобы отправить изображение в модель зрения или сгенерировать пакет эмбеддингов перед тем, как вы решите добавить кредиты на счет.

04Маршрутизация и отказоустойчивость для всех модальностей

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

Вы можете использовать объект provider в своем запросе, чтобы указать порядок провайдеров, разрешить фоллбэки, запретить сбор данных или отсортировать провайдеров по стоимости/задержке. Например, для запроса эмбеддингов вы можете указать:

terminaljson

{
  "model": "openai/text-embedding-3-small",
  "input": "Your text here",
  "provider": {
    "order": ["openai", "azure"],
    "allow_fallbacks": true,
    "data_collection": "deny"
  }
}

Эта же структура работает для эндпоинта генерации изображений /api/v1/images. Параметры provider.order, provider.allow_fallbacks, provider.only, provider.ignore и provider.sort применяются идентично. Если первый провайдер возвращает ошибку, запрос автоматически переключается на следующий в списке. Это критически важно для продакшн-приложений, где недоступность одного провайдера не должна останавливать весь сервис.

Кроме того, OpenRouter не делает наценки на цены провайдеров. Вы платите ровно столько, сколько указано в каталоге моделей. А благодаря функции «Zero Completion Insurance», неудачные запросы, которые не были завершены из-за сбоя провайдера, не тарифицируются. Это справедливо для всех модальностей.

05Что вы экономите, консолидируя API?

Экономия здесь не только в деньгах, но и в инженерных ресурсах. Один API-ключ, один счет, один формат запроса для всех пяти модальностей. Тот же Bearer-токен авторизует вызов зрения, TTS и эмбеддингов. Нет необходимости хранить отдельные ключи для каждого провайдера или проходить онбординг для каждого нового типа функциональности.

Консолидированное биллинг-отчетность означает, что все расходы на разные модальности попадают в один отчет OpenRouter. Вы можете легко сравнить, сколько стоила генерация изображений по сравнению с вычислением эмбеддингов, не экспортируя CSV-файлы из четырех разных дашбордов. Именно эта сложность с реконсилиацией данных часто становится камнем преткновения при использовании разрозненных API, как отмечали разработчики на Reddit.

06Ограничения, которые нужно учитывать

Несмотря на универсальность, у каждого подхода есть свои ограничения. Важно знать их заранее, чтобы правильно спроектировать архитектуру.

Отсутствие стриминга для эмбеддингов: Ответы по эмбеддингам приходят полностью готовыми, а не токенами. Планируйте синхронную обработку.
Детерминированность эмбеддингов: Один и тот же вход всегда дает один и тот же вектор. Используйте кэширование агрессивно, чтобы не платить за повторные вычисления.
Только Base64 для входного аудио: Аудио нельзя передать по URL. Локальные файлы нужно предварительно закодировать в base64.
Зависимость от провайдера для видео-URL: Поддержка URL для входного видео варьируется. Например, Gemini через AI Studio принимает только ссылки на YouTube.
Поддержка на уровне модели: Не каждая модель поддерживает каждую модальность. OpenRouter автоматически фильтрует модели по контенту, но вы должны выбирать модели, которые действительно поддерживают нужную вам задачу.
Лимиты бесплатного тарифа: Свободные модели имеют низкие дневные лимиты, которые возрастают после добавления кредитов.

Единый API оправдывает себя, когда вам нужно более одного типа медиа, когда замена модели — это изменение одной строки, или когда сбой провайдера не должен выводить функцию из строя. Если же ваше приложение — это просто один чат-бот на одной модели от одного провайдера, прямая интеграция может быть проще.

07Начните с одного вызова

Самый простой способ начать работу — отправить запрос на эмбеддинги. Вот пример на Python:

terminalpython

import requests

response = requests.post(
    "https://openrouter.ai/api/v1/embeddings",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "model": "openai/text-embedding-3-small",
        "input": "The quick brown fox jumps over the lazy dog"
    }
)

print(response.json()["data"][0]["embedding"][:5])

Или на TypeScript:

terminaltypescript

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY
});

const response = await openRouter.embeddings.generate({
  model: 'openai/text-embedding-3-small',
  input: 'The quick brown fox jumps over the lazy dog'
});

console.log(response.data[0].embedding);

Или через cURL:

terminalbash

curl https://openrouter.ai/api/v1/embeddings \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/text-embedding-3-small", "input": "The quick brown fox jumps over the lazy dog"}'

08Что это значит на практике

Концепция «одной API для всех модальностей» от OpenRouter — это не просто маркетинговый ход, а практическое решение для сложных AI-приложений. Она позволяет разработчикам сосредоточиться на логике приложения, а не на интеграционных сложностях. Используя единый базовый URL, вы получаете доступ к сотням моделей, настраиваете отказоустойчивость для всех типов запросов и упрощаете биллинг. Однако важно помнить об ограничениях: отсутствии стриминга для эмбеддингов, необходимости кодирования аудио в base64 и вариативности поддержки видео-URL. Понимание этих нюансов позволит вам построить надежную и эффективную AI-инфраструктуру, готовую к масштабированию.

Источник: OpenRouter ↗

Единый API для всех модальностей: как OpenRouter упрощает работу с AI