Разрешение СМИ

Параметр media_resolution управляет обработкой медиаданных, таких как изображения, видео и PDF-документы, API Gemini, определяя максимальное количество токенов, выделяемых для медиаданных, что позволяет найти баланс между качеством ответа, задержкой и стоимостью. Информация о различных настройках, значениях по умолчанию и их соответствии токенам представлена ​​в разделе « Количество токенов» .

Разрешение мультимедиа можно настроить двумя способами:

Разрешение отдельных частей носителя (только Gemini 3)

Gemini 3 позволяет задавать разрешение медиа для отдельных медиа-объектов в запросе, обеспечивая тонкую оптимизацию использования токенов. Вы можете комбинировать уровни разрешения в одном запросе. Например, использовать высокое разрешение для сложной диаграммы и низкое разрешение для простого контекстного изображения. Эта настройка переопределяет любую глобальную конфигурацию для конкретного компонента. Настройки по умолчанию см. в разделе «Количество токенов» .

Питон

from google import genai
from google.genai import types

# The media_resolution parameter for parts is currently only available in the v1alpha API version. (experimental)
client = genai.Client(
  http_options={
      'api_version': 'v1alpha',
  }
)

# Replace with your image data
with open('path/to/image1.jpg', 'rb') as f:
    image_bytes_1 = f.read()

# Create parts with different resolutions
image_part_high = types.Part.from_bytes(
    data=image_bytes_1,
    mime_type='image/jpeg',
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
)

model_name = 'gemini-3-pro-preview'

response = client.models.generate_content(
    model=model_name,
    contents=["Describe these images:", image_part_high]
)
print(response.text)

Javascript

// Example: Setting per-part media resolution in JavaScript
import { GoogleGenAI, MediaResolution, Part } from '@google/genai';
import * as fs from 'fs';
import { Buffer } from 'buffer'; // Node.js

const ai = new GoogleGenAI({ httpOptions: { apiVersion: 'v1alpha' } });

// Helper function to convert local file to a Part object
function fileToGenerativePart(path, mimeType, mediaResolution) {
    return {
        inlineData: { data: Buffer.from(fs.readFileSync(path)).toString('base64'), mimeType },
        mediaResolution: { 'level': mediaResolution }
    };
}

async function run() {
    // Create parts with different resolutions
    const imagePartHigh = fileToGenerativePart('img.png', 'image/png', Part.MediaResolutionLevel.MEDIA_RESOLUTION_HIGH);
    const model_name = 'gemini-3-pro-preview';
    const response = await ai.models.generateContent({
        model: model_name,
        contents: ['Describe these images:', imagePartHigh]
        // Global config can still be set, but per-part settings will override
        // config: {
        //   mediaResolution: MediaResolution.MEDIA_RESOLUTION_MEDIUM
        // }
    });
    console.log(response.text);
}
run();

ОТДЫХ

# Replace with paths to your images
IMAGE_PATH="path/to/image.jpg"

# Base64 encode the images
BASE64_IMAGE1=$(base64 -w 0 "$IMAGE_PATH")

MODEL_ID="gemini-3-pro-preview"

echo '{
    "contents": [{
      "parts": [
        {"text": "Describe these images:"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "'"$BASE64_IMAGE1"'",
          },
          "media_resolution": {"level": "MEDIA_RESOLUTION_HIGH"}
        }
      ]
    }]
  }' > request.json

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1alpha/models/${MODEL_ID}:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Глобальное разрешение СМИ

Вы можете задать разрешение по умолчанию для всех компонентов медиаконтента в запросе с помощью GenerationConfig . Эта функция поддерживается всеми мультимодальными моделями. Если запрос включает как глобальные, так и индивидуальные настройки , приоритет для данного элемента имеют индивидуальные настройки.

Питон

from google import genai
from google.genai import types

client = genai.Client()

# Prepare standard image part
with open('image.jpg', 'rb') as f:
    image_bytes = f.read()
image_part = types.Part.from_bytes(data=image_bytes, mime_type='image/jpeg')

# Set global configuration
config = types.GenerateContentConfig(
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
)

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

Javascript

import { GoogleGenAI, MediaResolution } from '@google/genai';
import * as fs from 'fs';

const ai = new GoogleGenAI({ });

async function run() {
   // ... (Image loading logic) ...

   const response = await ai.models.generateContent({
      model: 'gemini-2.5-flash',
      contents: ["Describe this image:", imagePart],
      config: {
         mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
      }
   });
   console.log(response.text);
}
run();

ОТДЫХ

# ... (Base64 encoding logic) ...

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [...],
    "generation_config": {
      "media_resolution": "MEDIA_RESOLUTION_HIGH"
    }
  }'

Доступные значения разрешения

API Gemini определяет следующие уровни разрешения мультимедиа:

  • MEDIA_RESOLUTION_UNSPECIFIED : Значение по умолчанию. Количество токенов для этого уровня значительно различается в Gemini 3 и более ранних моделях Gemini.
  • MEDIA_RESOLUTION_LOW : меньшее количество токенов, что приводит к более быстрой обработке и снижению затрат, но с меньшей детализацией.
  • MEDIA_RESOLUTION_MEDIUM : Баланс между детализацией, стоимостью и задержкой.
  • MEDIA_RESOLUTION_HIGH : Большее количество токенов, что обеспечивает большую детализацию для работы модели за счет увеличения задержки и затрат.
  • ( Скоро ) MEDIA_RESOLUTION_ULTRA_HIGH : Наибольшее количество токенов, необходимое для определенных случаев использования, например использования компьютера.

Точное количество токенов, генерируемых для каждого из этих уровней, зависит как от типа носителя (изображение, видео, PDF), так и от версии модели .

Количество токенов

В таблицах ниже приведены приблизительные количества токенов для каждого значения media_resolution и типа носителя для каждого семейства моделей.

Модели Джемини 3

MediaResolution Изображение Видео PDF
MEDIA_RESOLUTION_UNSPECIFIED (по умолчанию) 1120 70 560
MEDIA_RESOLUTION_LOW 280 70 280+ текстов на родном языке
MEDIA_RESOLUTION_MEDIUM 560 70 560+ текст на родном языке
MEDIA_RESOLUTION_HIGH 1120 280 1120 + родной текст

Модели Gemini 2.5

MediaResolution Изображение Видео PDF (сканированный) PDF (собственный)
MEDIA_RESOLUTION_UNSPECIFIED (по умолчанию) 256 + Панорамирование и сканирование (~2048) 256 256 + ОРС 256 + родной текст
MEDIA_RESOLUTION_LOW 64 64 64 + ОРС 64 + Родной текст
MEDIA_RESOLUTION_MEDIUM 256 256 256 + ОРС 256 + родной текст
MEDIA_RESOLUTION_HIGH 256 + Панорамирование и сканирование 256 256 + ОРС 256 + родной текст

Выбор правильного разрешения

  • По умолчанию ( UNSPECIFIED ): Начните с настройки по умолчанию. Она настроена на оптимальный баланс качества, задержки и стоимости для большинства распространённых сценариев использования.
  • LOW : Используйте в сценариях, где стоимость и задержка имеют первостепенное значение, а детализация не столь важна.
  • MEDIUM / HIGH : Увеличьте разрешение, если задача требует понимания сложных деталей на медиа-контенте. Это часто необходимо для сложного визуального анализа, чтения диаграмм или понимания объёмных документов.
  • Управление по частям (Gemini 3): используйте это для оптимизации использования токенов. Например, в подсказке с несколькими изображениями используйте HIGH для сложной диаграммы и LOW или MEDIUM для более простых контекстных изображений.

Рекомендуемые настройки

Ниже перечислены рекомендуемые настройки разрешения носителя для каждого поддерживаемого типа носителя.

Тип носителя Рекомендуемая настройка Макс. количество токенов Руководство по использованию
Изображения MEDIA_RESOLUTION_HIGH 1120 Рекомендуется для большинства задач анализа изображений для обеспечения максимального качества.
PDF-файлы MEDIA_RESOLUTION_MEDIUM 560 Оптимально для понимания документа; качество обычно достигает предела на medium . Повышение до high редко улучшает результаты распознавания текста для стандартных документов.
Видео (Общее) MEDIA_RESOLUTION_LOW (или MEDIA_RESOLUTION_MEDIUM ) 70 (на кадр) Примечание: для видео low и medium настройки обрабатываются одинаково (70 токенов) для оптимизации использования контекста. Этого достаточно для большинства задач распознавания и описания действий.
Видео (с большим количеством текста) MEDIA_RESOLUTION_HIGH 280 (на кадр) Требуется только в том случае, если случай использования предполагает чтение плотного текста (OCR) или мелких деталей на видеокадрах.

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

Сводка совместимости версий

  • Перечисление MediaResolution доступно для всех моделей, поддерживающих ввод мультимедиа.
  • Количество токенов, связанных с каждым уровнем перечисления, различается в моделях Gemini 3 и более ранних версиях Gemini.
  • Настройка media_resolution для отдельных объектов Part доступна только для моделей Gemini 3 .

Следующие шаги