Medienauflösung

Mit dem Parameter media_resolution wird gesteuert, wie die Gemini API Media-Eingaben wie Bilder, Videos, Audio und PDF-Dokumente verarbeitet. Dazu wird die maximale Anzahl von Tokens für Media-Eingaben festgelegt. So können Sie die Antwortqualität mit Latenz und Kosten in Einklang bringen. Bei visuellen und Dokument-Eingaben wird die Tokenzuweisung basierend auf der Auflösungseinstellung skaliert. Audioeingaben werden dagegen bei allen Auflösungsstufen mit einer festen Rate pro Sekunde tokenisiert. Informationen zu den verschiedenen Einstellungen, Standardwerten und wie sie mit Tokens zusammenhängen, finden Sie im Abschnitt Tokenanzahl.

Sie haben zwei Möglichkeiten, die Media-Auflösung zu konfigurieren:

• Pro Teil (nur Gemini 3)

• Global für eine gesamte generateContent-Anfrage (alle multimodalen Modelle)

Auflösung von Medien pro Teil (nur Gemini 3)

Mit Gemini 3 können Sie die Media-Auflösung für einzelne Media-Objekte in Ihrer Anfrage festlegen und so die Token-Nutzung optimieren. Sie können Auflösungsstufen in einer einzelnen Anfrage kombinieren. Verwenden Sie beispielsweise eine hohe Auflösung für ein komplexes Diagramm und eine niedrige Auflösung für ein Kontextbild. Diese Einstellung überschreibt jede globale Konfiguration für ein bestimmtes Teil. Informationen zu den Standardeinstellungen finden Sie im Abschnitt Tokenanzahl.

from google import genai
from google.genai import types

# The media_resolution parameter for parts is available in the v1beta API version.
client = genai.Client(
  http_options={
      'api_version': 'v1beta',
  }
)

# 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: 'v1beta' } });

// 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/v1beta/models/${MODEL_ID}:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Globale Media-Auflösung

Mit GenerationConfig können Sie eine Standardauflösung für alle Medienteile in einer Anfrage festlegen. Das wird von allen multimodalen Modellen unterstützt. Wenn eine Anfrage sowohl globale als auch einstellungsbezogene Einstellungen enthält, hat die einstellungsbezogene Einstellung für das jeweilige Element Vorrang.

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

Verfügbare Auflösungswerte

Die Gemini API definiert die folgenden Stufen für die Media-Auflösung:

• MEDIA_RESOLUTION_UNSPECIFIED: Die Standardeinstellung. Die Anzahl der Tokens für diese Stufe variiert erheblich zwischen Gemini 3 und früheren Gemini-Modellen.
• MEDIA_RESOLUTION_LOW: Geringere Anzahl von Tokens, was zu einer schnelleren Verarbeitung und niedrigeren Kosten führt, aber weniger Details liefert.
• MEDIA_RESOLUTION_MEDIUM: Ein ausgewogenes Verhältnis zwischen Detailgrad, Kosten und Latenz.
• MEDIA_RESOLUTION_HIGH: Höhere Anzahl von Tokens, die dem Modell mehr Details zur Verfügung stellen, was jedoch zu einer höheren Latenz und höheren Kosten führt.
• MEDIA_RESOLUTION_ULTRA_HIGH (nur pro Teil): Höchste Anzahl an Tokens, die für bestimmte Anwendungsfälle wie Computerverwendung erforderlich ist.

MEDIA_RESOLUTION_HIGH bietet in den meisten Anwendungsfällen die optimale Leistung.

Die genaue Anzahl der Tokens, die für jede dieser Ebenen generiert werden, hängt sowohl vom Medientyp (Bild, Video, Audio, PDF) als auch von der Modellversion ab.

Tokenanzahl

In den folgenden Tabellen sind die ungefähren Tokenzahlen für jeden media_resolution-Wert und Medientyp pro Modellfamilie zusammengefasst.

Gemini 3-Modelle

Gemini 2.5-Modelle

Die richtige Auflösung auswählen

• Standard (UNSPECIFIED): Beginnen Sie mit der Standardeinstellung. Es ist für die meisten gängigen Anwendungsfälle auf ein gutes Gleichgewicht zwischen Qualität, Latenz und Kosten abgestimmt.
• LOW:Für Szenarien, in denen Kosten und Latenz im Vordergrund stehen und detaillierte Informationen weniger wichtig sind.
• MEDIUM / HIGH:Erhöhe die Auflösung, wenn für die Aufgabe das Erkennen komplexer Details in den Media erforderlich ist. Das ist oft für komplexe visuelle Analysen, das Lesen von Diagrammen oder das Verstehen umfangreicher Dokumente erforderlich.
• ULTRA HIGH: Nur für die Einstellung „Pro Teil“ verfügbar. Empfohlen für bestimmte Anwendungsfälle wie die Verwendung am Computer oder wenn Tests eine deutliche Verbesserung gegenüber HIGH zeigen.
• Steuerung auf Teilebene (Gemini 3): Optimiert die Tokennutzung. Wenn Sie beispielsweise einen Prompt mit mehreren Bildern verwenden, können Sie HIGH für ein komplexes Diagramm und LOW oder MEDIUM für einfachere Kontextbilder verwenden.

Empfohlene Einstellungen

In den folgenden Listen sind die empfohlenen Einstellungen für die Media-Auflösung für die einzelnen unterstützten Medientypen aufgeführt.

Testen und bewerten Sie immer die Auswirkungen verschiedener Auflösungseinstellungen auf Ihre spezifische Anwendung, um den besten Kompromiss zwischen Qualität, Latenz und Kosten zu finden.

Beziehung zu Videoverarbeitungsmodi

Mit den media_resolution- und Verarbeitungsparametern werden verschiedene Aspekte der Videoeingabe gesteuert:

• Mit media_resolution wird die Auflösung jedes Frames gesteuert (Anzahl der Tokens pro Frame).
• Mit den Steuerelementen processing / media_processing wird festgelegt, welche Inhalte aus dem Video in den Kontext geladen werden.

Du kannst beides für denselben Videoeingang festlegen. Sie können beispielsweise die Verarbeitung durch KI-Agenten mit niedriger Media-Auflösung verwenden, um die Gesamtzahl der Tokens für ein langes Video zu minimieren.

Weitere Informationen zu den Videoverarbeitungsmodi finden Sie im Leitfaden Agentic Video Understanding.

Zusammenfassung der Versionskompatibilität

• Die MediaResolution-Enumeration ist für alle Modelle verfügbar, die Media-Eingabe unterstützen.
• Die Tokenanzahl, die mit jeder Enum-Ebene verknüpft ist, unterscheidet sich zwischen Gemini 3-Modellen und früheren Gemini-Versionen.
• Die Einstellung von media_resolution für einzelne Part-Objekte ist ausschließlich für Gemini 3-Modelle verfügbar.

Nächste Schritte

• Weitere Informationen zu den multimodalen Funktionen der Gemini API finden Sie in den Anleitungen zu Bildverständnis, Videoverständnis, Audioverständnis und Dokumentverständnis.