Параметр 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 | Изображение | Видео | |
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 .
Следующие шаги
- Узнайте больше о многомодальных возможностях API Gemini в руководствах по распознаванию изображений , видео и документов .