Изображения

Какие модели

Только tai-4.1 и tai-4.2 принимают изображения на входе; полную разбивку см. на странице Модели. Отправка изображения любой другой модели не приводит к прямой ошибке, но изображение молча игнорируется и учитывается только текстовая часть сообщения, поэтому стоит перепроверить поле модели, если понимание изображения не проявляется в ответе так, как ожидалось.

Формат содержимого

Для сообщения без изображения content — это обычная строка. Чтобы прикрепить изображение, content вместо этого становится массивом типизированных частей, смешивая одну или несколько частей text с одной или несколькими частями image_url:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Bu görselde ne var?"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSU..."}}
  ]
}

image_url.url принимает data URI в кодировке base64, а не обычную ссылку на размещённое изображение; API не загружает удалённый URL самостоятельно. Закодируйте байты изображения в base64, добавьте правильный MIME-тип в качестве префикса и отправьте всё это как значение url.

# Python: формирование data URI из локального файла
import base64

with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()
data_url = f"data:image/jpeg;base64,{b64}"

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

Принимаются PNG, JPEG и WebP. Используйте соответствующий MIME-тип в префиксе data URI (image/png, image/jpeg, image/webp), чтобы изображение декодировалось корректно.

Размер

Жёсткого ограничения на размер документа, проверяемого на стороне клиента, под которое нужно было бы подстраиваться, нет, но очень большие изображения добавляют заметную задержку (кодирование в base64 увеличивает размер примерно на треть, а всё тело запроса должно быть передано и обработано до начала генерации), и очень большие запросы с большей вероятностью будут отклонены промежуточной инфраструктурой ещё до того, как достигнут какого-либо ограничения на стороне модели. Уменьшение изображения до разрешения, реально полезного для задачи, вместо отправки оригинала в полном разрешении, обычно правильное решение и редко теряет что-то, что модель всё равно бы использовала.

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

Массив content одного сообщения может включать более одной части image_url, наряду с любым количеством частей text, от нуля и больше, в зависимости от потребности:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Bu iki görsel arasındaki fark ne?"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
  ]
}

В сочетании с вызовом инструментов

Изображение и tools могут присутствовать в одном и том же запросе; модель может вызвать инструмент, опираясь отчасти на то, что она видит в прикреплённом изображении, точно так же, как она делала бы это на основе одного лишь текста. О том, как устроен цикл вызова и ответа, см. в разделе Вызов инструментов.