DeepSeek опубликовал документацию по работе с изображениями для модели deepseek-v4-flash-vision-exp

Модель deepseek-v4-flash-vision-exp принимает на вход изображения вместе с текстом — с её помощью можно попросить описать картинку, распознать текст на скриншоте, проанализировать график и так далее.

Поддерживаемые форматы изображений: JPEG, PNG, GIF и WebP. Формат определяется по фактическому содержимому файла, а не по имени файла или заявленному MIME-типу.

Передача изображений

Передать изображение модели можно тремя способами. Все они используют стандартный формат Chat Completions, совместимый с OpenAI API, где поле content представляет собой массив блоков, а не обычную строку. Те же три метода доступны и в Responses API, где изображения передаются в частях содержимого типа input_image.

base_url для примеров ниже — https://api.deepseek.com.

1. Изображение в формате base64 (встроенное)

Изображение кодируется и встраивается прямо в запрос в виде data: URL. Это самый простой вариант для локальных файлов. Закодированные данные учитываются в лимите размера тела запроса в 48 МиБ (см. раздел «Лимиты»).

import base64
from openai import OpenAI

client = OpenAI(api_key="<DeepSeek API Key>", base_url="https://api.deepseek.com")

with open("image.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{b64}"},
                },
            ],
        }
    ],
)
print(response.choices[0].message.content)

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <DeepSeek API Key>" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_DATA>"}}
        ]
      }
    ]
  }'

2. Внешняя ссылка на изображение

Можно передать публично доступную ссылку по протоколу http(s) — модель сама загрузит изображение. Длина URL не должна превышать 8192 символов, размер файла изображения — не более 32 МиБ, а загрузка должна завершиться в течение 60 секунд. Если ссылка длиннее, стоит использовать base64 data URL или Files API.

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image."},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/image.jpg"},
                },
            ],
        }
    ],
)
print(response.choices[0].message.content)

3. Ссылка на файл, загруженный через Files API

Изображение можно загрузить один раз через Files API, а затем ссылаться на него по file_id в запросах. Это лучший вариант, если одно и то же изображение используется в нескольких запросах или если оно превышает лимит в 48 МиБ для встроенных данных. В отличие от встроенных изображений, файлы, на которые ссылаются через file_id, могут достигать 64 МиБ и не подпадают под ограничение в 32 МиБ на одно изображение.

Для этого используется блок содержимого типа file с полученным file_id (в формате file-api-...):

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
            ],
        }
    ],
)
print(response.choices[0].message.content)

Также блок file может содержать изображение прямо в base64 через поле file_data вместо file_id (эти два поля взаимоисключающие):

{
  "type": "file",
  "file_data": "data:image/jpeg;base64,<BASE64_DATA>",
  "filename": "image.jpg"
}

Уровень детализации

Для входных данных типа image_url можно опционально задать поле detail, которое управляет обработкой изображения:

{
  "type": "image_url",
  "image_url": {"url": "https://example.com/image.jpg", "detail": "low"}
}

Когда стоит использовать Files API

Встроенные изображения (base64 или file_data) учитываются в лимите размера тела запроса в 48 МиБ. Files API стоит рассмотреть, если:

• Один запрос превышает лимит размера тела.
• Изображение больше 32 МиБ — такой размер возможен только через Files API.
• Одно и то же изображение используется в нескольких запросах и повторная загрузка каждый раз нежелательна.

Расход токенов

Изображения преобразуются в токены в зависимости от их размеров, и эти токены тарифицируются вместе с текстовыми.

Перед инференсом каждое изображение автоматически изменяет размер:

• Изображения с общим числом пикселей примерно ниже 384×384 увеличиваются с сохранением пропорций.
• Более крупные изображения уменьшаются с сохранением пропорций так, чтобы общее число пикселей после изменения размера примерно соответствовало изображению 800×800.

В результате существует верхний предел в 384 токена на изображение: например, изображения размером 2000×2000 и 5000×5000 после изменения размера расходуют одинаковое число токенов. Если запрос содержит несколько изображений, каждое из них учитывается независимо по тому же правилу — отдельного расчёта для запросов с несколькими изображениями нет.

Для оценки стоимости изображения конкретного размера в токенах предусмотрен калькулятор на странице документации по расходу токенов.

Лимиты

Квоты хранения и загрузки файлов через Files API описаны в соответствующем разделе документации Files API.

Ограничения

• Изображения поддерживаются только в сообщениях с ролью user: изображения в сообщениях system или assistant приводят к ошибке 400.
• Изображения принимают только модели с поддержкой зрения (deepseek-v4-flash-vision-exp); остальные модели возвращают ошибку 400 («This model does not support image»).
• Пользовательский текст, содержащий зарезервированный служебный токен-плейсхолдер изображения, отклоняется с ошибкой 400.

Работа с изображениями через Anthropic API

Помимо описанного выше эндпоинта, совместимого с OpenAI, изображения можно передавать через эндпоинт /messages, совместимый с Anthropic API (base_url = https://api.deepseek.com/anthropic). Общая настройка описана в руководстве по Anthropic API.

Отличие — в структуре блока содержимого с изображением. Вместо image_url в Anthropic API используется блок image с объектом source, у которого поле type принимает одно из значений: base64, url или file:

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

message = client.messages.create(
    model="deepseek-v4-flash-vision-exp",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "<BASE64_DATA>",
                    },
                },
            ],
        }
    ],
)
print(message.content)

Три варианта source соответствуют трём методам, описанным выше для OpenAI API:

Работа с изображениями через Responses API

Модель deepseek-v4-flash-vision-exp также принимает изображения через Responses API, совместимый с OpenAI. Действуют те же три способа передачи (base64 data URL, внешняя ссылка http(s), file_id из Files API) и те же лимиты — отличается только структура части содержимого: изображения передаются в частях типа input_image, либо в сообщениях user / developer, либо в выводе элементов function_call_output / custom_tool_call_output:

response = client.responses.create(
    model="deepseek-v4-flash-vision-exp",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": "https://example.com/image.jpg", "detail": "low"},
            ],
        }
    ],
)
print(response.output_text)

Часть input_image поддерживает поле detail с той же семантикой, что описана выше (low / high / original / auto). Поле detail игнорируется, если изображение передано через file_id, а поля image_url и file_id взаимоисключающие.

Подробности о семантике полей, ограничениях (изображения в сообщениях system / assistant отклоняются с ошибкой 400) и изображениях в выводе инструментов приведены в руководстве по Responses API.