Разрешение медиафайла

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

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

• По частям (модели Gemini 4 и Gemini 3)

• Глобально для всего запроса generateContent (все мультимодальные модели).

Разрешение медиафайлов для каждой части (Gemini 4 и Gemini 3)

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

from google import genai
from google.genai import types

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

# 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-4-argon'

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

// 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: 'v1beta' } });

// 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-4-argon';
    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-4-argon"

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/v1beta/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-3.8-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

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-3.8-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-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [...],
    "generation_config": {
      "media_resolution": "MEDIA_RESOLUTION_HIGH"
    }
  }'

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

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

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

Обратите внимание, что MEDIA_RESOLUTION_HIGH обеспечивает оптимальную производительность в большинстве случаев.

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

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

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

Модели Gemini 3

Модели Gemini 2.5

Как выбрать разрешение

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

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

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

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

Связь с режимами обработки видео

Параметры media_resolution и обработки управляют разными аспектами видеовхода:

• media_resolution определяет разрешение каждого кадра (количество токенов на кадр).
• processing / media_processing позволяет выбрать, какой контент из видео будет загружен в контекст.

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

Подробнее о режимах обработки видео…

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

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

Дальнейшие действия

• Подробнее о мультимодальных возможностях Gemini API рассказывается в руководствах по пониманию изображений, видео, аудио и документов.