Мультимодальный ввод

Мультимодальный ввод позволяет моделям обрабатывать не только текст, но и изображения, аудио и другие формы контента. RouteAPI поддерживает передачу мультимодального контента через /v1/chat/completions (формат OpenAI) и /v1/messages (формат Claude), автоматически выполняя преобразование форматов между различными upstream-протоколами.

1. Обзор мультимодальности

Поддерживаемые типы модальностей

Тип модальности	Описание
Изображение (Vision)	Форматы PNG, JPEG, WebP, GIF для понимания изображений, OCR, анализа диаграмм
Аудио	Некоторые модели поддерживают аудиовход для понимания речи, транскрипции и т.д.
Видео	Некоторые модели поддерживают ввод видеокадров, разбивая видео на последовательности ключевых кадров

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

Поддерживаемые модели визуального распознавания

Следующие модели поддерживают ввод изображений (неполный список):

Семейство моделей	Типичный ID модели
OpenAI GPT-4 Vision	gpt-4o, gpt-4-turbo, gpt-5.5
Claude Vision	claude-sonnet-4-5, claude-opus-4-5
Gemini Vision	gemini-2.0-flash, gemini-2.5-pro
Azure OpenAI	azure-gpt-4o

Сначала убедитесь через эндпоинт списка моделей, что модель доступна в вашем аккаунте:

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Этот эндпоинт не возвращает поле с признаком поддержки ввода изображений. Наличие поддержки зрения определяйте по документации поставщика модели либо по одному реальному запросу с изображением.

2. Основы ввода изображений

Поддерживаемые форматы изображений

Формат	MIME Type	Описание
PNG	image/png	Формат без потерь, подходит для скриншотов и диаграмм
JPEG	image/jpeg	Сжатие с потерями, подходит для фотографий
WebP	image/webp	Современный формат с малым размером и высоким качеством
GIF	image/gif	Неанимированный формат (используется только первый кадр)

Ограничения размера изображений

Разные модели имеют разные ограничения размера изображений. Общие рекомендации:

Ограничение	Рекомендуемое значение	Описание
Размер одного изображения	< 20 МБ	Очень большие изображения увеличивают время обработки и стоимость
Разрешение изображения	Длинная сторона ≤ 2048px	Высокое разрешение автоматически масштабируется или обрабатывается по частям
После кодирования Base64	< 32 МБ	Общий размер запроса ограничен upstream-сервисом

Рекомендуется сжимать изображения перед загрузкой, снижая разрешение при сохранении читаемости, что сокращает время передачи и стоимость токенов.

Разрешение и соображения стоимости

Изображения преобразуются в токены для выставления счетов. Изображения высокого разрешения потребляют гораздо больше токенов, чем текст:

• Режим низкого разрешения (например, detail: "low" от OpenAI): фиксированно около 85 токенов/изображение.
• Режим высокого разрешения (например, detail: "high"): разбивается по размеру изображения; изображение 2048×2048 может потреблять 800-1500 токенов.

В production-среде выбирайте режим разрешения в соответствии с фактическими потребностями. Используйте режим low, когда точное распознавание не требуется.

3. Методы передачи изображений

Изображения можно передавать двумя способами: URL и кодирование Base64.

Метод URL

Передайте публично доступный URL изображения для получения upstream-сервисом модели:

Преимущества:

• Малый размер запроса, не использует вашу исходящую пропускную способность.
• Подходит для изображений, уже размещённых на CDN.

Недостатки:

• Изображение должно быть публично доступно; IP upstream-сервиса должны иметь к нему доступ.
• Если загрузка изображения не удалась (проблемы с сетью, аутентификация, истёкшая ссылка), запрос вернёт ошибку.

Случаи использования: изображения, уже размещённые на публичных хостингах или CDN, не требующие временной загрузки.

Метод кодирования Base64

Прочитайте изображение как бинарные данные, закодируйте в Base64 и встройте непосредственно в запрос:

Преимущества:

• Не требуется публично доступный URL, подходит для приватных изображений.
• Самодостаточный запрос, не зависит от доступности внешних сервисов.

Недостатки:

• Кодирование Base64 увеличивает размер данных примерно на 33%.
• Большой размер запроса, более длительное время загрузки.

Случаи использования: приватные изображения, загружаемые пользователем, локальные файлы, временные скриншоты без публичного URL.

Сравнение двух методов

Сравнение	Метод URL	Метод Base64
Размер запроса	Малый (только строка URL)	Большой (Base64 ~1.33× от исходного файла)
Скорость загрузки	Быстрая	Медленная
Доступность изображения	Должно быть публично доступно	Без требований, приватные изображения OK
Внешние зависимости	Зависит от сервера изображений и upstream-получения	Без внешних зависимостей
Случаи использования	Публичные хостинги, CDN	Загрузки пользователей, локальные файлы

4. Ввод изображений в формате OpenAI

В /v1/chat/completions изображения передаются через массив content, где каждый элемент — это блок контента, различаемый по type для текста и изображений.

Структура массива content

content может быть строкой (обычный текст) или массивом (мультимодальный):

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Что изображено на этой картинке?" },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg"
      }
    }
  ]
}

Структура image_url

Поля блока контента image_url:

Поле	Тип	Обязательно	Описание
type	string	Да	Фиксировано как "image_url"
image_url.url	string	Да	URL изображения или Data URI Base64
image_url.detail	string	Нет	Режим разрешения: "low", "high", "auto" (по умолчанию)

Параметр detail

detail управляет разрешением обработки изображения и стоимостью:

Значение	Поведение	Потребление токенов
"low"	Режим низкого разрешения, изображение уменьшается до фиксированного размера (например, 512×512)	Фиксированно около 85 токенов
"high"	Режим высокого разрешения, изображение обрабатывается по частям, сохраняет детали	По количеству частей, обычно сотни-тысячи токенов
"auto"	Модель выбирает автоматически (по умолчанию)	Зависит от стратегии модели

Пример разницы в стоимости:

• Простой скриншот с "low" может потребовать всего 85 токенов (~¥0.0001).
• То же изображение с "high" может потреблять 800 токенов (~¥0.001).

Для сценариев, не требующих распознавания мелкого текста или деталей (например, “какое это животное” или “какой цвет темы интерфейса”), достаточно "low". Используйте "high" только когда нужен OCR, чтение значений диаграмм или распознавание мелких объектов.

Полный пример метода URL

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
            "detail": "high"
          }
        },
        { "type": "text", "text": "Опишите содержание этого изображения" }
      ]
    }
  ]
}

Полный пример метода Base64

Base64 требует формата Data URI: data:<mime_type>;base64,<encoded_data>.

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
          }
        },
        { "type": "text", "text": "Какой текст содержится на этом изображении?" }
      ]
    }
  ]
}

Обратите внимание, что строка Base64 может быть очень длинной; приведённый выше пример усечён. В реальном использовании полное кодирование может составлять от нескольких сотен КБ до нескольких МБ.

5. Ввод изображений в формате Claude

В /v1/messages изображения передаются через блоки типа image в массиве content, со структурой, значительно отличающейся от формата OpenAI.

Структура массива content

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
      }
    },
    { "type": "text", "text": "Опишите это изображение" }
  ]
}

Структура source

Поле source указывает источник изображения двумя способами:

Метод Base64

Поле	Тип	Обязательно	Описание
type	string	Да	Фиксировано как "base64"
media_type	string	Да	MIME-тип, например image/jpeg, image/png
data	string	Да	Закодированные данные изображения Base64 (без префикса data:)

Обратите внимание, что Base64 формата Claude не требует префикса Data URI; передавайте закодированную строку напрямую.

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}

Метод URL

Поле	Тип	Обязательно	Описание
type	string	Да	Фиксировано как "url"
url	string	Да	Публично доступный URL изображения

{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
  }
}

Полный пример запроса

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
          }
        },
        { "type": "text", "text": "Что это за насекомое?" }
      ]
    }
  ]
}

6. Ввод изображений в формате Gemini

Нативный формат Gemini использует массив parts вместо content, со значительно отличающейся структурой. RouteAPI выполняет преобразование внутренне, поэтому при вызове моделей Gemini с использованием формата OpenAI или Claude вам не нужно беспокоиться о деталях нативного формата. Следующее приведено только для справки.

Массив parts

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Опишите это изображение" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRg..."
          }
        }
      ]
    }
  ]
}

inlineData (Base64)

Поле	Описание
inlineData.mimeType	MIME-тип
inlineData.data	Закодированные данные Base64

fileData (URI)

Gemini также поддерживает ссылку на файлы, загруженные в сервисы Google, через URI файла:

{
  "fileData": {
    "mimeType": "image/jpeg",
    "fileUri": "gs://bucket-name/path/to/image.jpg"
  }
}

На практике при вызове моделей Gemini через RouteAPI используйте формат OpenAI или Claude; RouteAPI автоматически выполнит преобразование.

7. Ввод нескольких изображений

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

Несколько изображений в одном запросе

Поместите несколько блоков изображений в массив content / parts:

Формат OpenAI:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Сравните различия между этими двумя изображениями" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/image1.jpg" }
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/image2.jpg" }
    }
  ]
}

Формат Claude:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Каковы сходства и различия этих двух изображений?" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/before.jpg" }
    },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/after.jpg" }
    }
  ]
}

Порядок изображений и ссылки

Модель понимает изображения в порядке массива. Если текст ссылается на “первое изображение” или “второе изображение”, модель сопоставит по порядку появления. Рекомендуется размещать пояснительный текст до или после всех изображений, а не вставлять между ними, для более ясной семантики:

{
  "content": [
    { "type": "text", "text": "Первое — скриншот пользовательского интерфейса, второе — макет дизайна. Пожалуйста, сравните различия и предоставьте предложения по модификации." },
    { "type": "image_url", "image_url": { "url": "..." } },
    { "type": "image_url", "image_url": { "url": "..." } }
  ]
}

Смешивание с текстом

Вы также можете чередовать текст и изображения для пошагового объяснения:

{
  "content": [
    { "type": "text", "text": "Это исходный интерфейс:" },
    { "type": "image_url", "image_url": { "url": "https://example.com/old.jpg" } },
    { "type": "text", "text": "Это улучшенный интерфейс:" },
    { "type": "image_url", "image_url": { "url": "https://example.com/new.jpg" } },
    { "type": "text", "text": "Пожалуйста, резюмируйте улучшения." }
  ]
}

Фактическая эффективность зависит от способности модели понимать порядок блоков контента; основные модели визуального распознавания обычно справляются с этим корректно.

8. Аудиовход

Некоторые модели поддерживают аудиовход для понимания речи, транскрипции, анализа эмоций и т.д. Текущая поддержка менее распространена, чем для изображений.

Поддерживаемые аудиоформаты

Зависит от конкретных моделей, распространённые форматы включают:

• WAV (audio/wav)
• MP3 (audio/mpeg)
• OGG (audio/ogg)
• FLAC (audio/flac)

Метод передачи аудио

Как и для изображений, аудио поддерживает методы URL и Base64. Пример формата OpenAI (при условии поддержки моделью):

{
  "role": "user",
  "content": [
    {
      "type": "input_audio",
      "input_audio": {
        "data": "<base64-encoded-audio>",
        "format": "wav"
      }
    },
    { "type": "text", "text": "Транскрибируйте это аудио и резюмируйте ключевые моменты" }
  ]
}

Фактические названия полей и структура зависят от протокола модели. Перед использованием обратитесь к документации выбранной модели или проверьте поле supports_audio_input через эндпоинт списка моделей.

9. Полные примеры приложений

Следующие примеры демонстрируют сквозную реализацию понимания изображений на curl, Python и Node.js.

Понимание и описание изображения

Дайте изображение и попросите модель описать его содержание.

curl (формат OpenAI, метод URL):

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
            }
          },
          { "type": "text", "text": "Подробно опишите содержание и атмосферу этого изображения" }
        ]
      }
    ]
  }'

Python (OpenAI SDK, метод Base64):

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

# Прочитать локальное изображение и закодировать в Base64
with open("image.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    },
                },
                {"type": "text", "text": "Что изображено на этой картинке?"},
            ],
        }
    ],
)

print(response.choices[0].message.content)

Node.js (пакет openai, метод URL):

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,
  baseURL: 'https://api.routeapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'image_url',
          image_url: {
            url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg',
          },
        },
        { type: 'text', text: 'Резюмируйте тему этого изображения в одном предложении' },
      ],
    },
  ],
});

console.log(response.choices[0].message.content);

Анализ диаграмм и визуализации данных

Загрузите скриншот диаграммы и попросите модель прочитать данные и проанализировать:

Python (формат Claude, Base64):

import base64
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai",
)

with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Какую тенденцию показывает эта диаграмма? Пожалуйста, извлеките ключевые точки данных и предоставьте анализ.",
                },
            ],
        }
    ],
)

print(message.content[0].text)

Извлечение текста OCR

Извлеките текстовое содержание из скриншотов или фотографий:

curl (формат OpenAI, высокое разрешение):

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/document.jpg",
              "detail": "high"
            }
          },
          {
            "type": "text",
            "text": "Извлеките весь текст из изображения, сохраняя исходный формат и структуру"
          }
        ]
      }
    ]
  }'

Для сценариев OCR используйте "detail": "high" для гарантии точности распознавания, особенно для мелкого или плотного текста.

Сравнительный анализ нескольких изображений

Сравните различия между двумя или более изображениями:

Python (формат OpenAI, несколько изображений):

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Сравните следующие два изображения и найдите 5 основных различий между ними:",
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/before.jpg"},
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/after.jpg"},
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

Смешанный диалог изображение-текст

Смешивайте изображения и текст в многоходовых диалогах:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/product.jpg"},
            },
            {"type": "text", "text": "Каковы основные характеристики этого продукта?"},
        ],
    }
]

response = client.chat.completions.create(model="gpt-4o", messages=messages)
messages.append(response.choices[0].message)
print("Первый ход:", response.choices[0].message.content)

# Продолжить задавать вопросы (обычный текст)
messages.append({"role": "user", "content": "Для какого типа пользователей он подходит?"})
response = client.chat.completions.create(model="gpt-4o", messages=messages)
print("Второй ход:", response.choices[0].message.content)

Изображения нужно передавать только один раз в первом ходе; в последующих ходах модель запомнит содержание изображения (в рамках контекстного окна) без необходимости повторной загрузки.

10. Лучшие практики

Оптимизация изображений

Выполните необходимую оптимизацию перед загрузкой изображений для снижения затрат и улучшения скорости отклика:

Оптимизация	Рекомендация
Размер	Держите длинную сторону в пределах 2048px, если не требуется распознавание большего количества деталей
Формат	Используйте PNG для скриншотов и диаграмм, JPEG для фотографий, WebP для максимального сжатия
Сжатие	Качество JPEG 80-90% достаточно, минимальная визуальная разница при значительном уменьшении размера
Обрезка	Удалите нерелевантные области (большие пустые пространства, водяные знаки, рамки), оставьте только ключевое содержание

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

Соображения стоимости

Стоимость мультимодального ввода в основном исходит от изображений:

Сценарий	Типичное потребление токенов	Оценка стоимости (GPT-4o)
Изображение низкого разрешения (detail: "low")	~85 токенов	$0.0001
Малое изображение высокого разрешения (500×500, detail: "high")	~200 токенов	$0.0003
Большое изображение высокого разрешения (2000×2000, detail: "high")	~800 токенов	$0.0012
Несколько изображений высокого разрешения (5 изображений, detail: "high")	~4000 токенов	$0.006

Конкретные тарифы зависят от выбранной модели; приведённое выше только для примера. Рекомендации для production:

1. По умолчанию используйте detail: "auto" или "low", позвольте модели или потребностям пользователя определять разрешение.
2. Используйте "high" только когда явно требуется точное распознавание (OCR, данные диаграмм, обнаружение мелких объектов).
3. Записывайте использование токенов для каждого запроса (поле usage ответа) для выявления аномалий стоимости.

Обработка ошибок

Мультимодальный ввод вводит дополнительные точки отказа, требующие целевой обработки:

Неподдерживаемый формат изображения

{
  "error": {
    "message": "Unsupported image format",
    "type": "invalid_request_error"
  }
}

Решение: Подтвердите, что MIME-тип корректен, или преобразуйте в PNG/JPEG.

Изображение слишком большое

{
  "error": {
    "message": "Image size exceeds limit",
    "type": "invalid_request_error"
  }
}

Решение: Сожмите изображение или уменьшите разрешение и повторите попытку.

URL недоступен

{
  "error": {
    "message": "Failed to fetch image from URL",
    "type": "invalid_request_error"
  }
}

Решение:

• Подтвердите, что URL публично доступен без аутентификации.
• Протестируйте, могут ли IP upstream-сервиса получить доступ к этому URL (брандмауэр, географические ограничения).
• Переключитесь на метод Base64, чтобы избежать зависимости от внешнего сервиса.

Сбой декодирования Base64

{
  "error": {
    "message": "Invalid base64 encoding",
    "type": "invalid_request_error"
  }
}

Решение: Проверьте, что кодирование Base64 полное и формат корректный (формат OpenAI требует префикс data:, формат Claude не требует).

Безопасность

Риск	Меры защиты
Утечка URL изображения	Убедитесь, что URL указывает на изображение без конфиденциальной информации, или используйте временные ссылки с аутентификацией
Атаки размером Base64	Ограничьте максимальный размер загружаемого изображения пользователем (например, 20 МБ) для предотвращения чрезмерно больших запросов
Инъекционные атаки	Не конкатенируйте напрямую URL изображений, загруженных пользователем, в системные команды или SQL
Галлюцинации модели	Результаты понимания изображений могут быть неточными; высокорисковые сценарии (медицина, право, финансы) требуют человеческой проверки

Примечания о совместимости

• Возможности визуального распознавания, поддерживаемые форматы изображений и максимальное количество изображений зависят от выбранной модели; тестируйте и проверяйте перед production.
• Параметр detail имеет смысл только в формате OpenAI; формат Claude не имеет соответствующего параметра.
• Разные модели имеют разные стратегии обработки разрешения; одно и то же изображение может потреблять значительно разное количество токенов в разных моделях.
• В потоковых ответах результаты обработки содержания изображения обычно возвращаются за один раз в начале или конце потока, а не посимвольно.
• Записывайте request ID, model ID, код статуса и использование токенов для каждого запроса, чтобы облегчить устранение проблем со стоимостью и качеством. См. Ошибки и отладка для подробностей.