Rozdzielczość multimediów

Parametr media_resolution określa, jak interfejs Gemini API przetwarza dane wejściowe multimediów, takie jak obrazy, filmy, dźwięk i dokumenty PDF, poprzez określenie maksymalnej liczby tokenów przydzielonych na potrzeby danych wejściowych multimediów. Dzięki temu możesz zrównoważyć jakość odpowiedzi z opóźnieniem i kosztem. O ile w przypadku danych wejściowych wizualnych i dokumentów przydział tokenów jest skalowany na podstawie ustawienia rozdzielczości, o tyle dane wejściowe audio są tokenizowane ze stałą szybkością na sekundę na wszystkich poziomach rozdzielczości. Więcej informacji o różnych ustawieniach, wartościach domyślnych i ich odpowiednikach w tokenach znajdziesz w sekcji Liczba tokenów.

Możesz skonfigurować rozdzielczość multimediów dla poszczególnych obiektów multimedialnych (elementów treści) w żądaniu (modele Gemini 4 i Gemini 3).

Rozdzielczość multimediów na element treści (modele Gemini 4 i Gemini 3)

Modele Gemini 4 i Gemini 3 umożliwiają ustawienie rozdzielczości multimediów dla poszczególnych obiektów multimedialnych w żądaniu, co pozwala na precyzyjną optymalizację wykorzystania tokenów. W jednym żądaniu możesz łączyć różne poziomy rozdzielczości. Na przykład możesz użyć wysokiej rozdzielczości w przypadku złożonego diagramu i niskiej rozdzielczości w przypadku prostego obrazu kontekstowego.

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)

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();

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)
    }
}

# 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"
      }
    ]
  }'

Dostępne wartości rozdzielczości

Interfejs Gemini API definiuje te poziomy rozdzielczości multimediów:

• unspecified (nieokreślona): ustawienie domyślne. Liczba tokenów na tym poziomie znacznie się różni w zależności od tego, czy używasz modeli Gemini 4/3 czy wcześniejszych modeli Gemini.
• low (niska): mniejsza liczba tokenów, co przekłada się na szybsze przetwarzanie i niższe koszty, ale z mniejszą ilością szczegółów.
• medium (średnia): równowaga między szczegółami, kosztem i opóźnieniem.
• high (wysoka): większa liczba tokenów, co zapewnia modelowi więcej szczegółów, ale kosztem większego opóźnienia i wyższych kosztów.
• ultra_high (tylko w przypadku elementu treści): największa liczba tokenów wymagana w określonych przypadkach użycia, np. w przypadku korzystania z komputera.

Pamiętaj, że w większości przypadków użycia optymalną wydajność zapewnia ustawienie high.

Dokładna liczba tokenów wygenerowanych na każdym z tych poziomów zależy zarówno od typu multimediów (obraz, film, dźwięk, PDF), jak i od wersji modelu.

Liczba tokenów

W tabelach poniżej znajdziesz podsumowanie przybliżonej liczby tokenów dla każdej wartości media_resolution i typu multimediów w przypadku poszczególnych rodzin modeli.

Modele Gemini 4 i Gemini 3

Wybór odpowiedniej rozdzielczości

• Domyślna (unspecified): zacznij od ustawienia domyślnego. Jest ono dostosowane do zapewnienia równowagi między jakością, opóźnieniem i kosztem w większości typowych przypadków użycia.
• low (niska): używaj w sytuacjach, w których najważniejsze są koszt i opóźnienie, a szczegółowość jest mniej istotna.
• medium (średnia) / high (wysoka): zwiększ rozdzielczość, gdy zadanie wymaga zrozumienia złożonych szczegółów w multimediach. Jest to często konieczne w przypadku złożonej analizy wizualnej, odczytywania wykresów lub zrozumienia dokumentów o dużej ilości tekstu.
• ultra_high (bardzo wysoka) – dostępna tylko w przypadku ustawienia na element treści. Zalecana w określonych przypadkach użycia, np. w przypadku korzystania z komputera, lub gdy testy wykazują wyraźną poprawę w porównaniu z ustawieniem high.
• Kontrola na element treści (Gemini 4 i Gemini 3): optymalizuje wykorzystanie tokenów. Na przykład w przypadku prompta z kilkoma obrazami użyj ustawienia high w przypadku złożonego diagramu oraz ustawienia low lub medium w przypadku prostszych obrazów kontekstowych.

Zalecane ustawienia

Poniżej znajdziesz zalecane ustawienia rozdzielczości multimediów dla każdego obsługiwanego typu multimediów.

Zawsze testuj i oceniaj wpływ różnych ustawień rozdzielczości na aplikację, aby znaleźć najlepszy kompromis między jakością, opóźnieniem i kosztem.

Związek z trybami przetwarzania wideo

Parametry media_resolution i przetwarzania kontrolują różne aspekty danych wejściowych wideo:

• media_resolution określa rozdzielczość każdej klatki (liczbę tokenów na klatkę).
• processing / media_processing określa, które treści z filmu są wczytywane do kontekstu.

Oba parametry możesz ustawić w tych samych danych wejściowych wideo. Na przykład możesz użyć przetwarzania agentowego z niską rozdzielczością multimediów, aby zminimalizować całkowite wykorzystanie tokenów w przypadku długiego filmu.

Więcej informacji o trybach przetwarzania wideo znajdziesz w przewodniku Rozumienie wideo przez agenta.

Podsumowanie zgodności wersji

• Ustawienie resolution w przypadku poszczególnych elementów treści jest obsługiwane w modelach Gemini 4 i Gemini 3.

Dalsze kroki

• Więcej informacji o możliwościach multimodalnych interfejsu Gemini API znajdziesz w przewodnikach Rozumienie obrazów, Rozumienie wideo, Rozumienie dźwięku, i Rozumienie dokumentów.