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 festgelegt, die für Media-Eingaben zugewiesen werden. So können Sie die Antwortqualität gegen Latenz und Kosten abwägen. Bei visuellen Eingaben und Dokumenteingaben wird die Tokenzuweisung basierend auf der Auflösungseinstellung skaliert. Bei Audioeingaben werden Tokens jedoch mit einer festen Rate pro Sekunde über alle Auflösungsstufen hinweg zugewiesen. Informationen zu den verschiedenen Einstellungen, Standardwerten und der entsprechenden Anzahl von Tokens finden Sie im Abschnitt Tokenanzahl.

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

• Pro Teil (Gemini 4- und Gemini 3-Modelle)

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

Media-Auflösung pro Teil (Gemini 4 und Gemini 3)

Mit Gemini 4 und Gemini 3 können Sie die Media-Auflösung für einzelne Media-Objekte in Ihrer Anfrage festlegen und so die Tokennutzung detailliert optimieren. Sie können in einer einzelnen Anfrage verschiedene Auflösungsstufen kombinieren. Beispielsweise können Sie eine hohe Auflösung für ein komplexes Diagramm und eine niedrige Auflösung für ein Kontextbild verwenden. Diese Einstellung überschreibt jede globale Konfiguration für einen bestimmten 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-4-argon'

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-4-argon';
    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-4-argon"

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 Media-Teile in einer Anfrage festlegen. Diese Funktion wird von allen multimodalen Modellen unterstützt. Wenn eine Anfrage sowohl globale als auch teilspezifische Einstellungen enthält, hat die teilspezifische Einstellung für dieses bestimmte 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 Tokenanzahl für diese Stufe variiert erheblich zwischen Gemini 3 und früheren Gemini-Modellen.
• MEDIA_RESOLUTION_LOW: Niedrigere Tokenanzahl, was zu einer schnelleren Verarbeitung und niedrigeren Kosten führt, aber weniger Details bietet.
• MEDIA_RESOLUTION_MEDIUM: Ein ausgewogenes Verhältnis zwischen Detailgenauigkeit, Kosten und Latenz.
• MEDIA_RESOLUTION_HIGH: Höhere Tokenanzahl, die mehr Details für das Modell bietet, aber zu einer höheren Latenz und höheren Kosten führt.
• MEDIA_RESOLUTION_ULTRA_HIGH (nur pro Teil): Höchste Tokenanzahl, die für bestimmte Anwendungsfälle wie die Computernutzung erforderlich ist.

Beachten Sie, dass MEDIA_RESOLUTION_HIGH für die meisten Anwendungsfälle die optimale Leistung bietet.

Die genaue Anzahl der Tokens, die für jede dieser Stufen 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 Tokenanzahlen 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. Sie ist für die meisten Anwendungsfälle auf ein gutes Gleichgewicht zwischen Qualität, Latenz und Kosten abgestimmt.
• LOW: Verwenden Sie diese Einstellung für Szenarien, in denen Kosten und Latenz im Vordergrund stehen und feine Details weniger wichtig sind.
• MEDIUM / HIGH: Erhöhen Sie die Auflösung, wenn die Aufgabe das Verständnis komplexer Details in den Media-Inhalten erfordert. Dies ist häufig 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 Computernutzung oder wenn Tests eine deutliche Verbesserung gegenüber HIGH zeigen.
• Steuerung pro Teil (Gemini 4 und Gemini 3): Optimiert die Tokennutzung. Verwenden Sie beispielsweise in einer Eingabeaufforderung mit mehreren Bildern HIGH für ein komplexes Diagramm und LOW oder MEDIUM für einfachere Kontextbilder.

Empfohlene Einstellungen

In der folgenden Liste sind die empfohlenen Einstellungen für die Media-Auflösung für jeden unterstützten Medientyp 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

Die Parameter media_resolution und `processing` steuern verschiedene Aspekte der Videoeingabe:

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

Sie können beide für dieselbe Videoeingabe festlegen. Beispielsweise können Sie die Agentenverarbeitung mit einer niedrigen 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 Agentenbasierte Videoverarbeitung.

Zusammenfassung der Versionskompatibilität

• Die MediaResolution-Enumeration ist für alle Modelle verfügbar, die Media-Eingaben unterstützen.
• Die Tokenanzahlen, die mit den einzelnen Enumerationsstufen verknüpft sind, unterscheiden sich zwischen Gemini 4-/Gemini 3-Modellen und früheren Gemini-Versionen.
• Das Festlegen von media_resolution für einzelne Part-Objekte wird von Gemini 4- und Gemini 3-Modellen unterstützt.

Nächste Schritte

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