Изображения в OpenAI-совместимом API: URL, Base64 и проверка мультимодальной модели (2026)

Успешный текстовый запрос ещё не означает, что провайдер действительно поддерживает изображения. Мультимодальный запрос зависит от формата сообщения, возможностей модели, размера файла и доступности источника изображения.

1. Проверьте три условия

Убедитесь, что Base URL поддерживает совместимый путь, выбранная модель принимает изображения, а провайдер разрешает публичные URL или data URL. Обычно сообщение выглядит так:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Опиши изображение одним предложением"},
    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
  ]
}

2. Первый тест через публичный URL

URL должен быть доступен серверам провайдера. Локальный компьютер, внутренний адрес и закрытое облачное хранилище не подойдут. При ошибке 400 сначала проверьте JSON и ID модели; при ошибке загрузки проверьте публичность URL, сертификат, MIME-тип и размер файла.

3. Локальный файл в Base64

Если изображение нельзя открыть извне, передайте data URL. Base64 увеличивает размер тела запроса, поэтому в production нужно ограничить размер и формат файла.

import base64, mimetypes
from pathlib import Path
path = Path('photo.jpg')
mime = mimetypes.guess_type(path.name)[0] or 'image/jpeg'
encoded = base64.b64encode(path.read_bytes()).decode('ascii')
image_url = f'data:{mime};base64,{encoded}'

Наиболее распространённые MIME-типы: image/jpeg, image/png и image/webp. Не полагайтесь только на расширение файла: перед отправкой проверьте сигнатуру файла и отклоняйте неподдерживаемые форматы.

4. Почему текстовая модель отвечает ошибкой параметров

OpenAI-совместимый протокол описывает форму запроса, но не гарантирует наличие vision-возможностей. Проверьте отдельно текстовую модель, vision-модель и изображения разных размеров. Записывайте ID модели, статус HTTP и задержку ответа: так можно отличить отсутствие поддержки модели от ошибки маршрутизации у провайдера.

5. Безопасность и стоимость

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

Начните с маленького публичного изображения, затем переходите к Base64 и добавляйте в production проверки размера, формата, тайм-аутов и конфиденциальности.