Rozdzielczość multimediów

Parametr media_resolution określa, jak interfejs Gemini API przetwarza dane wejściowe multimediów, takie jak obrazy, filmy i dokumenty PDF. Określa maksymalną liczbę tokenów przydzielonych na dane wejściowe multimediów, co pozwala zrównoważyć jakość odpowiedzi z opóźnieniem i kosztem. Więcej informacji o różnych ustawieniach, wartościach domyślnych i ich odpowiednikach w tokenach znajdziesz w sekcji Liczba tokenów.

Rozdzielczość multimediów możesz skonfigurować na 2 sposoby:

• dla każdej części (tylko Gemini 3),

• globalnie dla całego żądania generateContent (wszystkie modele multimodalne).

Rozdzielczość multimediów dla każdej części (tylko Gemini 3)

Gemini 3 umożliwia 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 mieszać poziomy rozdzielczości. Możesz na przykład użyć wysokiej rozdzielczości w przypadku złożonego diagramu i niskiej rozdzielczości w przypadku prostego obrazu kontekstowego. To ustawienie zastępuje dowolną konfigurację globalną dla określonej części. Ustawienia domyślne znajdziesz w sekcji Liczba tokenów.

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.1-pro-preview'

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: '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.1-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.1-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

Globalna rozdzielczość multimediów

Za pomocą GenerationConfig możesz ustawić domyślną rozdzielczość dla wszystkich części multimedialnych w żądaniu. Jest to obsługiwane przez wszystkie modele multimodalne. Jeśli żądanie zawiera ustawienia globalne i ustawienia dla każdej części, w przypadku danego elementu pierwszeństwo ma ustawienie dla każdej części.

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

Dostępne wartości rozdzielczości

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

• MEDIA_RESOLUTION_UNSPECIFIED: ustawienie domyślne. Liczba tokenów na tym poziomie znacznie różni się w zależności od tego, czy używasz Gemini 3, czy wcześniejszych modeli Gemini.
• MEDIA_RESOLUTION_LOW: mniejsza liczba tokenów, co przyspiesza przetwarzanie i obniża koszty, ale zmniejsza szczegółowość.
• MEDIA_RESOLUTION_MEDIUM: równowaga między szczegółowością, kosztem i opóźnieniem.
• MEDIA_RESOLUTION_HIGH: większa liczba tokenów, co zapewnia modelowi więcej szczegółów, ale zwiększa opóźnienie i koszt.
• MEDIA_RESOLUTION_ULTRA_HIGH (tylko dla każdej części): największa liczba tokenów, wymagana w określonych przypadkach użycia, np. podczas korzystania z komputera.

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

Dokładna liczba tokenów generowanych na każdym z tych poziomów zależy zarówno od typu multimediów (obraz, film, PDF), jak i 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 każdej rodziny modeli.

Modele Gemini 3

Modele Gemini 2.5

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: używaj w sytuacjach, w których najważniejsze są koszt i opóźnienie, a szczegółowość jest mniej istotna.
• MEDIUM / HIGH: 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 zawierających dużo tekstu.
• ULTRA HIGH – dostępne tylko w przypadku ustawienia dla każdej części. Zalecane w określonych przypadkach użycia, np. podczas korzystania z komputera, lub gdy testy wykazują wyraźną poprawę w porównaniu z ustawieniem HIGH.
• Sterowanie dla każdej części (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 konkretną aplikację, aby znaleźć najlepszy kompromis między jakością, opóźnieniem i kosztem.

Podsumowanie zgodności wersji

• Wyliczenie MediaResolution jest dostępne we wszystkich modelach obsługujących dane wejściowe multimediów.
• Liczba tokenów powiązana z każdym poziomem wyliczenia różni się w zależności od tego, czy używasz modeli Gemini 3, czy wcześniejszych wersji Gemini.
• Ustawienie media_resolution w poszczególnych obiektach Part jest dostępne tylko w modelach Gemini 3.

Dalsze kroki

• Więcej informacji o możliwościach multimodalnych interfejsu Gemini API znajdziesz w przewodnikach dotyczących rozpoznawania obrazów, rozumienia filmów i rozumienia dokumentów.