OpenAI Vision API: как отправить изображение и получить ответ

Для анализа изображения в новом коде используйте Responses API: он принимает текстовый вопрос и изображение в одном input, а результат можно получить как текст. Images API предназначен прежде всего для создания изображений. Chat Completions тоже умеет работать с картинками, но для новой интеграции логично начать с Responses API и проверить в каталоге моделей, доступна ли выбранная vision-capable-модель вашему проекту. Официальное руководство OpenAI по изображениям и vision

Ниже — минимальный запрос на Python. Перед запуском задайте OPENAI_API_KEY в окружении и выберите вместо YOUR_VISION_MODEL модель с поддержкой изображений, доступную вашему проекту:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="YOUR_VISION_MODEL",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Что изображено на фотографии? Перечисли только хорошо различимые объекты.",
                },
                {
                    "type": "input_image",
                    "image_url": "https://example.com/photo.jpg",
                },
            ],
        }
    ],
)

print(response.output_text)

В официальном Python SDK OpenAI итоговый текст доступен в response.output_text. Это удобная точка входа для обычного ответа; если приложению нужно различать текст, вызовы инструментов и другие части результата, разбирайте структурированный объект ответа.

После первого успешного запроса можно отдельно решить пользовательскую задачу, которая не относится к API-балансу. Для пользователей из России предложения ChatGPT и других сервисов собраны в каталоге Amber Market. Это отдельная покупка, а не пополнение OpenAI API: перед заказом проверьте условия и наличие, выберите карточку, подтвердите email, сверьте итоговую сумму и результат на нужном аккаунте. Магазин указывает оплату через СБП без автоматических списаний.

Как передать изображение

Responses API принимает три формы изображения: полностью квалифицированный URL, Base64-кодированный data URL и file_id, созданный через Files API.

Публичный URL

{
    "type": "input_image",
    "image_url": "https://cdn.example.com/invoices/invoice-42.jpg",
}

URL должен быть доступен сервису OpenAI и вести непосредственно к изображению. Ссылка на страницу просмотра файла с авторизацией в браузере для этого не подходит. Для закрытого объектного хранилища можно выдать временный URL или сначала загрузить файл через Files API.

Data URL с Base64

Для локального файла сформируйте data URL и сохраните правильный MIME-тип:

import base64
from openai import OpenAI


def image_as_data_url(path: str, mime_type: str = "image/jpeg") -> str:
    with open(path, "rb") as image_file:
        encoded = base64.b64encode(image_file.read()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


client = OpenAI()
image_url = image_as_data_url("photo.jpg")

response = client.responses.create(
    model="YOUR_VISION_MODEL",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Опиши сцену на изображении."},
                {"type": "input_image", "image_url": image_url},
            ],
        }
    ],
)

print(response.output_text)

Data URL не требует публиковать файл, но увеличивает размер запроса. Изображения считаются billable input tokens и влияют на TPM, поэтому контролируйте размер и не отправляйте один и тот же файл заново при каждом повторе без необходимости.

file_id из Files API

Если изображение уже загружено через Files API, передайте его идентификатор:

{
    "type": "input_image",
    "file_id": "file-...",
}

Так удобно разделить загрузку и анализ в фоновом сервисе. Связку «идентификатор файла — исходный пользовательский файл» храните у себя: одного file_id недостаточно для бизнес-аудита результата.

Несколько изображений передаются несколькими элементами input_image в том же content:

"content": [
    {"type": "input_text", "text": "Сравни эти изображения и назови различия."},
    {"type": "input_image", "image_url": "https://example.com/before.jpg"},
    {"type": "input_image", "image_url": "https://example.com/after.jpg"},
]

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

Параметр detail

detail управляет предварительной обработкой изображения. Поддерживаемые значения зависят от модели, а если параметр не указан, в Responses API используется auto:

{
    "type": "input_image",
    "image_url": "https://example.com/receipt.jpg",
    "detail": "high",
}

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

Тот же запрос в JavaScript

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "YOUR_VISION_MODEL",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "Прочитай крупный заголовок на изображении." },
        {
          type: "input_image",
          image_url: "https://example.com/poster.png",
        },
      ],
    },
  ],
});

console.log(response.output_text);

В Node.js локальный файл можно прочитать через readFile, преобразовать в Base64 и собрать data URL. В браузере секретный API-ключ нельзя бездумно отправлять на клиент: запрос к OpenAI должен проходить через ваш сервер или другой контролируемый backend-маршрут.

Если нужна общая настройка API и первый обычный запрос на Python, см. инструкцию по первому запросу к GPT API. Здесь добавляется именно input_image, а не повторяется настройка проекта.

Как проверить результат

Успешный HTTP-статус ещё не означает, что приложение получило полезный ответ. Проверяйте результат последовательно:

1. Обработайте исключения SDK и ошибки API: неверную модель, недоступный файл, ошибку формата и лимиты нельзя маскировать пустой строкой.
2. Убедитесь, что response.output_text существует и после удаления пробелов не пуст.
3. Проверьте, что текст отвечает на заданный вопрос, а не только подтверждает получение изображения.
4. Для важных данных вручную сверьте ответ с оригиналом и сохраните исходное изображение вместе с результатом.

Простой защитный слой в Python:

try:
    response = client.responses.create(
        model="YOUR_VISION_MODEL",
        input=[
            {
                "role": "user",
                "content": [
                    {"type": "input_text", "text": "Какой номер заказа указан на документе?"},
                    {"type": "input_image", "image_url": image_url},
                ],
            }
        ],
    )
except Exception as error:
    raise RuntimeError(f"Vision API request failed: {error}") from error

answer = (response.output_text or "").strip()
if not answer:
    raise RuntimeError("Vision API returned an empty text answer")

print(answer)

Эта проверка подтверждает транспорт и наличие текста, но не истинность распознавания. Vision-модель может ошибиться на мелком тексте, сложной сцене или неоднозначном объекте. Для медицинских, юридических, финансовых и других критичных решений её ответ нельзя использовать как единственное основание: нужна проверка человеком или специализированная процедура валидации.

Итак, для новой интеграции выберите доступную vision-capable-модель, передайте через Responses API input_text вместе с input_image, используйте URL, data URL или file_id, а затем проверьте и сам текстовый результат, и его соответствие оригиналу. Модель помогает разобрать изображение; решение о том, что делать с этим разбором, остаётся на стороне вашего кода.