Vision: как отправить изображение в нейросеть через API

Чтобы отправить изображение в нейросеть через API, передайте его в user-сообщении частью типа image_url — публичной HTTPS-ссылкой или строкой base64. Запрос уходит на стандартный /v1/chat/completions и работает с официальными SDK OpenAI без доработок. Нужна лишь модель, принимающая изображения на вход: в каталоге Hubris таких больше полутора сотен — от GPT и Claude до Gemini и Qwen, с оплатой в рублях.

Формат запроса: image_url внутри messages

В обычном текстовом запросе поле content — строка. В мультимодальном оно становится массивом частей: текстовые блоки {"type": "text"} и изображения {"type": "image_url"} в свободном порядке. Минимальный запрос через curl выглядит так:

curl -s https://api.hubris.pw/v1/chat/completions \
  -H "Authorization: Bearer sk-gw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Что изображено на картинке?" },
          {
            "type": "image_url",
            "image_url": { "url": "https://example.com/photo.jpg" }
          }
        ]
      }
    ]
  }'

Ответ приходит в обычном формате chat completions: текст модели — в choices[0].message.content, расход токенов — в usage. Полная схема параметров — в справочнике POST /v1/chat/completions, подробности мультимодального ввода — в документации Vision.

В одном сообщении допускается несколько изображений — добавляйте части по одной. Модель увидит все картинки и сможет ссылаться на них в ответе: «на первом скриншоте..., на втором...».

URL или base64 — и какие есть лимиты

Передать изображение можно двумя способами.

Публичная ссылка. Картинка по URL скачивается на стороне модели, поэтому ссылка должна открываться без авторизации. Типичный лимит размера — 5–20 МБ в зависимости от модели; поддерживаются JPEG, PNG, WebP и GIF.

Base64 data URL. Если файл не лежит в открытом доступе — пришёл от пользователя, сгенерирован на лету, хранится в закрытом хранилище, — закодируйте его в base64 и передайте прямо в запросе:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Формат строки: data:image/<mime>;base64,<данные>. Учтите: base64 увеличивает объём примерно на треть, поэтому большие файлы стоит сжать перед отправкой. На количество токенов способ доставки не влияет — тарифицируется само изображение, а не длина JSON.

Часть моделей понимает необязательный параметр detail рядом с url: "low" — беглый взгляд в низком разрешении, "high" — внимательное чтение мелких деталей, "auto" — модель решает сама (значение по умолчанию).

Пример на Python: разбор скриншота

Понадобится аккаунт Hubris: регистрация — по коду из письма, без пароля; API-ключ создаётся в личном кабинете в разделе «Ключи»; баланс пополняется в разделе «Биллинг» — через СБП, банковской картой или по счёту для юридических лиц. Путь от регистрации до первого запроса по шагам описан в гайде о доступе к Claude API из России — он одинаков для всех моделей каталога.

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

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hubris.pw/v1",
    api_key="sk-gw-...",  # ваш ключ из раздела «Ключи»
)

with open("screenshot.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Это скриншот веб-формы. Перечисли поля, "
                            "заполненные с ошибками, и текст сообщений интерфейса.",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{encoded}",
                        "detail": "high",
                    },
                },
            ],
        }
    ],
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, "входных токенов")

Тот же код подходит для фотографий: замените файл и текст вопроса — например, «что на фото и в каком состоянии объект». Отдельная библиотека для работы с изображениями не нужна: достаточно пакета openai и замены base_url.

OCR и разбор документов: практические кейсы

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

• Распознавание сканов и фотографий документов. Модель возвращает текст со скана договора или снимка страницы — в том числе там, где классический OCR спотыкается о наклон, тень или нестандартный шрифт.
• Извлечение полей из чеков и счетов. Попросите вернуть JSON с полями «сумма», «дата», «продавец» — и получите структуру, готовую к записи в базу. В связке со структурированным выводом схема ответа гарантирована.
• Таблицы и диаграммы. Модель пересказывает график словами или переводит таблицу с картинки в markdown либо CSV.
• Скриншоты интерфейсов. Проверка вёрстки, разбор сообщений об ошибках, описание шагов воспроизведения дефекта по картинке.

Для документов с мелким текстом ставьте detail: "high" и отправляйте изображение в исходном разрешении: сильное сжатие «съедает» мелкие символы, и качество распознавания заметно падает.

Какие модели принимают изображения и сколько это стоит

Изображения на вход принимает любая модель, у которой в карточке (GET /v1/models) поле input_modalities содержит "image". В каталоге моделей есть фильтр по входным модальностям: отметьте «изображение» — останутся только подходящие варианты. На июнь 2026 года таких моделей в каталоге больше 160.

Картинка тарифицируется как дополнительные входные токены — обычно от нескольких сотен до пары тысяч на изображение в зависимости от модели и разрешения; точное число видно в usage.prompt_tokens ответа. Несколько ориентиров по ценам (актуальны на июнь 2026 года, точные значения — в каталоге):

Модель	Вход, ₽ за 1 млн токенов	Выход, ₽ за 1 млн токенов
qwen/qwen3-vl-8b-instruct	8,49	53,05
openai/gpt-4o-mini	15,92	63,66
google/gemini-2.5-flash	31,83	265,27
anthropic/claude-haiku-4.5	106,11	530,53
openai/gpt-5.2	185,69	1 485,48
anthropic/claude-sonnet-4.6	318,32	1 591,59

Для первых экспериментов в каталоге есть и бесплатные модели с пометкой :free, принимающие изображения, — например, google/gemma-4-31b-it:free. Качество и стабильность у них скромнее платных, но проверить гипотезу хватит.

Частые вопросы

Сколько токенов расходует одна картинка?

Зависит от модели, разрешения и параметра detail. Маленькое изображение в detail: "low" — порядка сотни входных токенов, скриншот стандартного разрешения — несколько сотен, большой 2K-скриншот в "high" — до нескольких тысяч. Точный расход всегда виден в поле usage.prompt_tokens ответа.

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

Да. Добавьте в массив content несколько частей image_url — модель увидит все картинки и сможет сравнивать их между собой, например скриншоты «до» и «после».

Почему модель не видит картинку по ссылке?

Чаще всего ссылка недоступна снаружи: требует авторизацию, ведёт во внутреннюю сеть или отдаёт HTML вместо изображения. Картинка по URL скачивается на стороне модели анонимно, поэтому приватные файлы передавайте как base64 data URL.

Работает ли Vision в потоковом режиме?

Да. stream: true действует с мультимодальными запросами так же, как с текстовыми: ответ приходит частями, изображения лишь увеличивают входную часть запроса.