Параметр media_resolution определяет, как Gemini API обрабатывает медиафайлы, например изображения, видео, аудио и PDF-документы. Он задает максимальное количество токенов, выделенных для медиафайлов, что позволяет вам найти баланс между качеством ответа, задержкой и стоимостью. При обработке визуальных и текстовых данных количество токенов зависит от разрешения, а при обработке аудиоданных – от фиксированной частоты токенизации в секунду независимо от разрешения. Информацию о разных настройках, значениях по умолчанию и их соответствии токенам можно найти в разделе Количество токенов.
Вы можете настроить разрешение для отдельных медиаобъектов (контента) в запросе (модели Gemini 4 и Gemini 3).
Разрешение медиаконтента для каждого объекта (модели Gemini 4 и Gemini 3)
Модели Gemini 4 и Gemini 3 позволяют задавать разрешение для отдельных медиаобъектов в запросе, что дает возможность точно оптимизировать использование токенов. В одном запросе можно использовать разные уровни разрешения. Например, для сложной диаграммы можно использовать высокое разрешение, а для простого контекстного изображения – низкое.
Python
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/image.jpg")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": myfile.uri,
"mime_type": myfile.mime_type,
"resolution": "high"
}
]
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/image.jpg",
config: { mime_type: "image/jpeg" },
});
const interaction = await ai.interactions.create({
model: "gemini-3.8-flash",
input: [
{ type: "text", text: "Describe this image:" },
{
type: "image",
uri: myfile.uri,
mime_type: myfile.mimeType,
resolution: "high"
}
],
});
console.log(interaction.output_text);
}
await main();
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;
Client client = new Client();
Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
ImageContent.builder()
.uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
.mimeType(ImageContentMimeType.IMAGE_JPEG)
.build();
List<Content> contents = Arrays.asList(textContent, imageContent);
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.ofContent(contents))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
Проложить маршрут
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput([]interactions.Content{
interactions.NewContent(interactions.TextContent{
Text: "Describe the details in this high-resolution image.",
}),
interactions.NewContent(interactions.ImageContent{
URI: genai.Ptr(uploadedFile.URI),
MimeType: interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
Resolution: interactions.MediaResolutionHigh.ToPointer(),
}),
}),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
REST
# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.8-flash",
"input": [
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": "YOUR_FILE_URI",
"mime_type": "image/jpeg",
"resolution": "high"
}
]
}'
Доступные значения разрешения
Gemini API определяет следующие уровни разрешения медиаконтента:
unspecified– значение по умолчанию. Количество токенов для этого уровня значительно различается между Gemini 4/3 и более ранними моделями Gemini.low– меньшее количество токенов, что приводит к более быстрой обработке и снижению затрат, но при этом уменьшается детализация.medium– баланс между детализацией, стоимостью и задержкой.high– большее количество токенов, что позволяет модели работать с более подробными данными, но увеличивает задержку и стоимость.ultra_high(только для отдельных элементов контента) – наибольшее количество токенов, необходимое для определенных вариантов использования, например использования компьютера.
Обратите внимание, что high обеспечивает оптимальную производительность в большинстве случаев.
Точное количество токенов, генерируемых для каждого из этих уровней, зависит как от типа медиаконтента (изображение, видео, аудио, PDF), так и от версии модели.
Количество токенов
В таблицах ниже приведены приблизительные значения количества токенов для каждого значения media_resolution и типа медиаконтента для каждого семейства моделей.
Модели Gemini 4 и Gemini 3
| MediaResolution | Изображение | Видео | Аудио | |
|---|---|---|---|---|
unspecified (по умолчанию) |
1120 | 70 | 25 (в секунду) | 560 |
low |
280 | 70 | 25 (в секунду) | 280 + нативный текст |
medium |
560 | 70 | 25 (в секунду) | 560 + нативный текст |
high |
1120 | 280 | 25 (в секунду) | 1120 + нативный текст |
ultra_high |
2240 | Н/Д | – | Н/Д |
Как выбрать разрешение
- По умолчанию (
unspecified). Начните с настроек по умолчанию. Он обеспечивает оптимальное соотношение качества, задержки и стоимости для большинства распространенных вариантов использования. low– используется, когда стоимость и задержка имеют первостепенное значение, а детализация не так важна.medium/high. Увеличьте разрешение, если задача требует понимания сложных деталей в медиафайле. Это часто требуется для сложного визуального анализа, чтения диаграмм или понимания документов с большим количеством информации.ultra_high– доступно только для настройки отдельных объектов контента. Рекомендуется для определенных случаев использования, например при работе на компьютере, или если тестирование показывает, что этот режим значительно лучше, чемhigh.- Управление на уровне контента (Gemini 4 и Gemini 3). Оптимизирует использование токенов. Например, если в запросе несколько изображений, используйте
highдля сложной диаграммы иlowилиmediumдля более простых контекстных изображений.
Рекомендуемые настройки
Ниже приведены рекомендуемые настройки разрешения для каждого поддерживаемого типа медиаконтента.
| Тип медиа | Рекомендуемые настройки | Максимальное количество токенов | Рекомендации по использованию |
|---|---|---|---|
| Изображения | high |
1120 | Рекомендуется для большинства задач по анализу изображений, чтобы обеспечить максимальное качество. |
| PDF-файлы | medium |
560 | Оптимально подходит для понимания документов. Качество обычно достигает максимума при значении medium. Увеличение до high редко улучшает результаты оптического распознавания символов для стандартных документов. |
| Видео (общие) | low или medium |
70 (на кадр) | Примечание. Для видео настройки low и medium обрабатываются одинаково (70 токенов), чтобы оптимизировать использование контекста. Этого достаточно для большинства задач по распознаванию и описанию действий. |
| Видео (много текста) | high |
280 (на кадр) | Требуется, только если вариант использования включает чтение плотного текста (OCR) или мелких деталей в кадрах видео. |
| Аудио | unspecified (по умолчанию) |
25 (в секунду) | Аудио токенизируется с фиксированной скоростью 25 токенов в секунду для всех поддерживаемых настроек разрешения (unspecified, low, medium и high). |
Всегда тестируйте и оценивайте влияние различных настроек разрешения на ваше приложение, чтобы найти наилучший компромисс между качеством, задержкой и стоимостью.
Связь с режимами обработки видео
Параметры media_resolution и обработки управляют разными аспектами входного видео:
media_resolutionопределяет разрешение каждого кадра (количество токенов на кадр).processing/media_processingпозволяет выбрать, какой контент из видео будет загружен в контекст.
Оба параметра можно задать для одного и того же видеовхода. Например, вы можете использовать обработку с помощью агента с низким разрешением медиафайла, чтобы минимизировать общее использование токенов для длинного видео.
Подробную информацию о режимах обработки видео можно найти в руководстве Распознавание видео с помощью агентов.
Сводка по совместимости версий
- Задавать
resolutionдля отдельных элементов контента можно в моделях Gemini 4 и Gemini 3.
Дальнейшие действия
- Подробнее о мультимодальных возможностях Gemini API рассказывается в руководствах по пониманию изображений, видео, аудио и документов.