Генерация и анализ изображений через OpenRouter API

Представьте себе типичный сценарий разработки современного AI-приложения. Вы успешно интегрировали провайдера генерации изображений, ваши пользователи создают потрясающие арты, и всё работает безупречно. Но через неделю перед вами встает новая задача: нужно не просто создавать картинки, но и «читать» их. Возможно, это OCR для распознавания данных с загруженных чеков, быстрый анализ объектов перед сохранением актива или автоматическая генерация альтернативного текста для обеспечения доступности (accessibility). Это совершенно другая задача. С большинством существующих провайдеров это означает подключение второго SDK, получение второго API-ключа и настройку второго биллингового аккаунта. Хаос в архитектуре и лишние расходы.

Здесь на сцену выходит OpenRouter. Платформа предлагает элегантное решение: обе задачи — и генерация, и анализ изображений — выполняются через один базовый URL (https://openrouter.ai/api/v1), с использованием одного API-ключа и одной единой счета. Для генерации изображения вы отправляете POST-запрос к эндпоинту /images. Для анализа (чтения) изображения вы отправляете его в модель компьютерного зрения (vision model) на стандартном эндпоинте /chat/completions. Каталог моделей за этими эндпоинтами охватывает ведущих производителей AI, а маршрутизация запросов и механизм отказоустойчивости (failover) работают для изображений так же надежно, как и для текстовых чатов.

В этой статье мы подробно разберем, как эффективно использовать эту мощную функциональность. Мы рассмотрим доступные модели, покажем примеры кода на Python, JavaScript и cURL, объясним нюансы маршрутизации и поможем избежать распространенных ошибок. Это руководство предназначено для разработчиков, которые хотят максимизировать эффективность своих AI-интеграций, не усложняя архитектуру лишними зависимостями.

01Единая точка входа: Генерация и понимание через один ключ

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

Давайте сравним два основных типа задач, которые вы можете решать:

Генерация (создание изображения): Вы отправляете текстовый промпт модели генерации. На выходе получаете массив данных, содержащий закодированные в base64 изображения. Эндпоинт: POST /api/v1/images.
Понимание (анализ изображения): Вы отправляете изображение (через URL или base64) вместе с текстовым запросом модели компьютерного зрения. На выходе получаете текстовое описание, распознанный текст или классификацию. Эндпоинт: POST /api/v1/chat/completions.

Такой подход не только упрощает разработку, но и оптимизирует затраты. Поскольку оба типа запросов проходят через один аккаунт, вы можете гибко управлять лимитами и отслеживать расходы в едином интерфейсе. Это особенно важно для стартапов и небольших команд, где каждый доллар на инфраструктуру на счету.

02Каталог моделей: Кто производит изображения?

За кулисами OpenRouter работает с ведущими лабораториями и компаниями в области AI. Каталог генерации изображений включает в себя такие мощные модели, как:

Google: Семейство Gemini Image (например, Gemini 2.0 Flash).
OpenAI: GPT Image.
Black Forest Labs: FLUX — одна из самых популярных моделей для высококачественной генерации.
xAI: Grok Imagine.
ByteDance: Seedream.
Microsoft: MAI-Image.
Специализированные провайдеры: Recraft, Krea и Sourceful (Riverflow).

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

Генерация и анализ изображений через единый API: Полное руководство

Через код: Используйте запрос GET /api/v1/images/models для получения списка всех моделей генерации с их поддерживаемыми параметрами. Также можно использовать общий каталог: GET /api/v1/models?output_modalities=image.
Через веб-интерфейс: На странице «Models» есть фильтр, который визуально показывает доступные модели сгенерации, позволяя сразу увидеть цены.
Через Chatroom: Если вы хотите протестировать промпты перед интеграцией в приложение, используйте кнопку генерации изображений в интерфейсе чата. Это позволяет экспериментировать без написания кода.

💡

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

03Как генерировать изображения: Практическое руководство

Процесс генерации изображения через OpenRouter прост и интуитивно понятен. Вам нужно отправить POST-запрос на эндпоинт /api/v1/images, указав модель и промпт. Изображения возвращаются в массиве data в формате base64.

Ниже приведен пример использования cURL для генерации изображения:

terminalbash

curl https://openrouter.ai/api/v1/images \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemini-2.5-flash-image",
  "prompt": "A watercolor fox curled asleep in autumn leaves"
}'

Для разработчиков на Python пример выглядит следующим образом:

terminalpython

import os
import requests

api_key = os.environ["OPENROUTER_API_KEY"]
response = requests.post(
    "https://openrouter.ai/api/v1/images",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "model": "google/gemini-2.5-flash-image",
        "prompt": "A watercolor fox curled asleep in autumn leaves"
    },
)
response.raise_for_status()
result = response.json()
print(len(result["data"][0]["b64_json"]))  # длина base64-закодированных байтов изображения

И для JavaScript/TypeScript с использованием официального SDK:

terminaljavascript

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

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

const result = await openRouter.images.generate({
  imageGenerationRequest: {
    model: 'google/gemini-2.5-flash-image',
    prompt: 'A watercolor fox curled asleep in autumn leaves'
  },
});

if ('data' in result) {
  console.log(result.data[0].b64Json?.length); // длина base64-закодированных байтов
}

Каждая запись в массиве data содержит изображение в поле b64_json и поле media_type (обычно image/png, но векторные модели Recraft могут возвращать image/svg+xml). Поле usage сообщает о количестве токенов и стоимости запроса. Вы можете запросить до 10 изображений за один вызов с помощью параметра n (хотя не все провайдеры поддерживают n > 1). Рекомендуется итерировать по массиву data, а не жестко кодировать индекс 0, чтобы избежать ошибок.

Управление размерами, качеством и форматом

Тело запроса принимает специфические для изображений поля, позволяющие тонко настраивать результат:

resolution: Нормализованный уровень качества: 512, 1K, 2K, 4K.
aspect_ratio: Соотношение сторон от 1:1 до расширенных значений, таких как 21:9. Провайдеры могут ограничивать этот список своими поддерживаемыми наборами.
quality: Уровень качества: auto, low, medium или high.
output_format: Формат вывода: png, jpeg, webp или svg (только для векторных моделей).
input_references: Референсные изображения (URL или base64) для работы в режиме image-to-image.

Проверяйте supported_parameters конкретной модели через GET /api/v1/images/models, чтобы узнать, какие параметры она принимает. Провайдеры также могут принимать специфические опции через provider.options. Модели с поддержкой потоковой передачи (supports_streaming: true) могут отправлять частичные изображения через SSE, если установлен флаг stream: true.

04Как анализировать или «читать» изображения

Для задач понимания изображений (OCR, описание, классификация) используется стандартный эндпоинт чата /chat/completions с моделями компьютерного зрения (vision models). Вы отправляете массив сообщений, содержащий текстовую часть и часть с image_url.

Пример на cURL для распознавания текста на чеке:

terminalbash

curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}}
      ]
    }
  ]
}'

На Python это выглядит так:

terminalpython

import os
import requests

api_key = os.environ["OPENROUTER_API_KEY"]
response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "model": "google/gemini-2.5-flash",
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this image?"},
                    {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}}
                ]
            }
        ],
    },
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

Ответ возвращается в виде стандартного текстового завершения, где ответ модели находится в поле choices[0].message.content. Поле image_url принимает как публичные URL, так и data URL в формате base64. Для локальных файлов, которые вы не хотите хостить публично, base64 является правильным выбором.

⚠️

Важно: Порядок и тип контента. Отправляйте текстовую часть первой, затем изображения. Альтернативно, поместите изображения в системный промпт, если они должны предшествовать обращению пользователя. Поддерживаемые типы изображений: image/png, image/jpeg, image/webp и image/gif. Для PDF-файлов используйте тип контента file, а не предварительно рендерите страницы в изображения.

05Генерация или понимание: какой путь выбрать?

Понимание разницы между генерацией и анализом критически важно для правильной архитектуры. Используйте генерацию, когда результатом является новый визуальный актив: макеты, рекламные креативы, иллюстрации, которые начинаются как текстовый промпт и заканчиваются пикселями. Эндпоинт: /api/v1/images.

Используйте понимание, когда у вас уже есть изображение и вам нужна извлеченная из него информация: OCR для форм, альтернативный текст для доступности, обнаружение дефектов на конвейере или простая классификация. Эндпоинт: /chat/completions.

Существует также третий вариант для приложений, где сам разговор должен решать, когда требуется изображение. Инструмент сервера openrouter:image_generation (в бета-версии) позволяет модели чата генерировать изображение в середине разговора без явного вызова этого кода вашим приложением. Добавьте { "type": "openrouter:image_generation" } в массив tools запроса, и модель сама определит, когда вызвать этот инструмент. По умолчанию используется openai/gpt-5-image.

06Маршрутизация и отказоустойчивость для изображений

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

Пример конфигурации провайдера:

terminaljson

{
  "model": "google/gemini-2.5-flash-image",
  "prompt": "A minimalist logo for a coffee roaster",
  "provider": {
    "order": ["google-ai-studio", "google-vertex"],
    "allow_fallbacks": true
  }
}

Этот запрос предпочитает один провайдер и переходит к следующему в случае сбоя. Для вызовов зрения на /chat/completions используется полный объект провайдера для чата, включая data_collection: "deny". OpenRouter не добавляет наценку к ценам провайдеров. Согласно политике Zero Completion Insurance, запрос на генерацию изображения, который не завершается из-за сбоя, не взимается с вас.

07Бесплатная генерация изображений: мифы и реальность

На данный момент бесплатной генерации изображений нет. Бесплатный тариф OpenRouter покрывает модели с суффиксом :free (50 запросов в день, 20 RPM, без кредитной карты), но ни одна модель генерации изображений пока не имеет этого суффикса. Поэтому генерация изображений требует наличия кредитного баланса на аккаунте.

Однако тестирование обходится недорого. Цены на генерацию на моделях с низкой стоимостью начинаются примерно с одного цента за изображение. Каждый ответ содержит поле usage.cost, которое сообщает, сколько стоил запрос. Это позволяет точно контролировать расходы. Бесплатный пул моделей меняется, поэтому стоит периодически проверять /models?output_modalities=image на предмет новых предложений.

08Как исправить ошибку «no endpoints found that support image input»

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

Чтобы исправить это, выполните три шага:

Подтвердите поддержку модели: Её поле input_modalities должно включать image. Текстовые модели никогда не будут иметь этого.
Найдите модель с поддержкой зрения: Выполните запрос GET /api/v1/models?input_modalities=image или используйте фильтр модальностей ввода на странице Models.
Обновите строку модели: Измените имя модели в вашем запросе и отправьте его снова.

Сродные ошибки, такие как no endpoints found that support tool use, работают аналогичным образом. Имя ошибки указывает на несоответствующее требование; смягчите его или выберите комбинацию модели и провайдера, которая ему соответствует.

09Лимиты и особенности, которые нужно учитывать

При планировании интеграции обратите внимание на следующие ограничения:

Вывод в Base64: Сгенерированные изображения возвращаются в data[].b64_json как байты base64, а не как URL хостинга файла. Декодирование и хранение — ваша задача.
Поддержка направления варьируется: Модели генерации живут на /api/v1/images; ввод зрения требует модели, чьи input_modalities включают image на /chat/completions. Несоответствия проявляются как ошибка «no endpoints found».
Поддержка параметров варьируется: Значения aspect_ratio, n > 1, потоковая передача и специфические опции провайдера различаются для каждого эндпоинта. Проверяйте supported_parameters в GET /api/v1/images/models.
Биллинг «всё или ничего»: Генерация оплачивается полностью при завершении или не оплачивается вовсе при сбое; частичной оплаты за изображение не существует.

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

Интеграция OpenRouter для работы с изображениями открывает перед разработчиками широкие возможности для создания многофункциональных AI-приложений. Используя один API-ключ и один базовый URL, вы можете легко переключаться между генерацией нового контента и анализом существующего. Это упрощает архитектуру, снижает затраты на управление ключами и упрощает биллинг.

Для российских разработчиков важно отметить, что доступ к OpenRouter из РФ может требовать использования VPN или прокси-серверов, так как некоторые международные сервисы могут ограничивать доступ. Однако сам API работает стабильно, а механизм маршрутизации позволяет обходить возможные задержки или недоступность отдельных провайдеров. Локальный запуск моделей через OpenRouter не поддерживается, так как это облачный сервис, но вы можете использовать полученные base64-изображения локально в своих приложениях.

Начните с каталога моделей, протестируйте промпты в Chatroom и подключите вызовы с помощью приведенных выше фрагментов кода. Экспериментируйте с разными моделями, чтобы найти идеальный баланс между качеством, скоростью и стоимостью для ваших конкретных задач.

11Часто задаваемые вопросы

Могу ли я генерировать и читать изображения через один API?
Да, через один базовый URL и один API-ключ. Для генерации отправьте модель и промпт на https://openrouter.ai/api/v1/images. Для чтения отправьте его как image_url модели зрения на /chat/completions. Оба запроса попадают в один счет.

Какие модели генерации изображений доступны в OpenRouter?
Каталог включает Google (семейство Gemini Image), OpenAI (GPT Image), Black Forest Labs (FLUX), xAI (Grok Imagine), ByteDance (Seedream), Microsoft (MAI-Image), Recraft, Krea и Sourceful (Riverflow). Отфильтруйте /models?output_modalities=image или просмотрите коллекцию моделей изображений для получения актуального списка и цен.

Как исправить ошибку «no endpoints found that support image input»?
Вы отправили image_url модели, которая не принимает ввод изображений. Подтвердите, что input_modalities модели включают image, найдите модель с поддержкой зрения через GET /api/v1/models?input_modalities=image и обновите строку модели в запросе.

Есть ли бесплатный способ генерации изображений в OpenRouter?
На данный момент нет. Бесплатный тариф (50 запросов/день, 20 RPM, без кредитной карты) покрывает модели с суффиксом :free, и ни одна модель генерации изображений пока не имеет его, поэтому генерация требует кредитного баланса. Модели с низкой стоимостью начинаются примерно с одного цента за изображение.

Как возвращаются сгенерированные изображения?
В массиве data ответа; каждая запись содержит b64_json с base64-закодированными байтами изображения и поле media_type (обычно image/png). Запросите до 10 изображений за вызов с помощью параметра n и итерируйте по data, а не жестко кодируйте индекс 0.

Источник: OpenRouter ↗

Генерация и анализ изображений через единый API: Полное руководство