Создание API чата для распознавания изображений (Потоковый / Непотоковый режим)

Данный API поддерживает мультимодальный ввод, позволяя пользователям отправлять как текст, так и URL-адреса изображений в диалоге. Модель генерирует соответствующий ответ на основе введенного промпта и содержимого изображения. Поддерживается потоковый вывод (Streaming) для обеспечения более плавного взаимодействия с пользователем.

• URL-адрес API: https://api.codingplanx.ai/v1/chat/completions
• Метод запроса: POST
• Официальная документация: OpenAI Chat Completion API

---

Параметры запроса

Заголовки (Headers)

Тело запроса (Body)

Структура объекта messages

Каждый элемент в списке сообщений содержит следующие поля:

• role: (string) Роль автора сообщения, возможные значения: system, user, assistant, tool.
• content: (string или array) Содержимое сообщения.
  • В режиме распознавания изображений content является массивом, содержащим объекты с типами text и image_url.

---

Пример запроса

Смешанный запрос с текстом и изображением (JSON)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Вы — профессиональный помощник по анализу изображений."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Что находится на этой картинке? Пожалуйста, опишите подробно."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}

---

Описание ответа

Непотоковый ответ (stream: false)

Пример ответа

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "На этой фотографии изображено безмятежное озеро на фоне горного хребта."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 35,
        "total_tokens": 155
    }
}

Потоковый ответ (stream: true)

Если параметр stream установлен в true, API возвращает ответ в формате text/event-stream. Каждая строка начинается с префикса data: , а ее содержимое представляет собой строку JSON. Последним сообщением в потоке всегда будет data: [DONE].

---

Частые вопросы (FAQ)

Q1: Как загрузить изображение локально вместо передачи URL-адреса? A: Данный API в первую очередь поддерживает URL-адреса изображений. Если у вас есть только локальное изображение, рекомендуется сначала загрузить его на ваш фотохостинг или в облачное хранилище объектов (OSS). В качестве альтернативы вы можете преобразовать изображение в строку с кодировкой Base64 в формате data:image/jpeg;base64,{base64_encode_data} и передать её в поле url.

Q2: Почему в моем потоковом запросе не возвращается статистика usage? A: В стандартном потоковом протоколе, совместимом с OpenAI, статистика usage обычно возвращается только в последнем фрагменте данных (chunk) или при передаче специального параметра stream_options. Убедитесь, что версия вашей модели поддерживает возврат счетчика токенов в потоковом режиме.

Q3: Каковы ограничения на размер и формат изображений для распознавания? A: Обычно поддерживаются форматы PNG, JPEG, WEBP и GIF (без анимации). Рекомендуемый размер файла изображения — не более 20 МБ. Для достижения наилучших результатов распознавания рекомендуется использовать изображения с разрешением 512x512 пикселей и выше.

Q4: Что делать, если мой запрос возвращает ошибку "401 Unauthorized"? A: Убедитесь, что вы правильно передали заголовок Authorization. Формат должен быть Bearer плюс ваш API KEY. Также проверьте, действителен ли сам ключ и достаточно ли средств на вашем балансе.

Q5: Влияет ли параметр temperature на результаты распознавания изображений? A: Да. Параметр temperature влияет на языковую креативность модели при описании изображения. Если вам нужно очень объективное и строгое описание, рекомендуется установить более низкое значение (например, 0.2); если вы хотите получить более живое и интересное описание, установите более высокое значение (например, 0.8).

Q6: Как обработать распознавание нескольких изображений одновременно? A: Вы можете добавить несколько объектов с типом image_url в массив messages.content. Модель попытается понять и проанализировать содержимое всех предоставленных изображений одновременно.