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

Параметр 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 Изображение Видео Аудио PDF
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.

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