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 können die Media-Auflösung für einzelne Media-Objekte (Inhaltselemente) in Ihrer Anfrage konfigurieren (nur Gemini 3).

Auflösung von Medien pro Inhaltselement (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 detailliert optimieren. Sie können Auflösungsstufen in einer einzelnen Anfrage kombinieren. So können Sie beispielsweise für ein komplexes Diagramm eine hohe Auflösung und für ein einfaches Kontextbild eine niedrige Auflösung verwenden.

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

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

Verfügbare Auflösungswerte

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

• unspecified: Die Standardeinstellung. Die Anzahl der Tokens für diese Stufe variiert erheblich zwischen Gemini 3 und früheren Gemini-Modellen.
• low: Geringere Anzahl von Tokens, was zu einer schnelleren Verarbeitung und niedrigeren Kosten führt, aber weniger Details liefert.
• medium: Ein ausgewogenes Verhältnis zwischen Detailgrad, Kosten und Latenz.
• 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.
• ultra_high (nur pro Inhaltselement): Höchste Anzahl an Tokens, die für bestimmte Anwendungsfälle wie die Computernutzung erforderlich ist.

high bietet für die meisten Anwendungsfälle 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

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öhen Sie die Auflösung, wenn die Aufgabe das Erfassen komplexer Details in den Media erfordert. Das ist oft für komplexe visuelle Analysen, das Lesen von Diagrammen oder das Erfassen von dichten Dokumenten erforderlich.
• ultra_high: Nur für die Einstellung pro Inhaltselement verfügbar. Empfohlen für bestimmte Anwendungsfälle wie die Verwendung auf einem Computer oder wenn Tests eine deutliche Verbesserung gegenüber high zeigen.
• Steuerung pro Inhaltselement (Gemini 3): Optimiert die Tokennutzung. Verwenden Sie beispielsweise in einem Prompt mit mehreren Bildern high für ein komplexes Diagramm und low oder medium für einfachere Kontextbilder.

Empfohlene Einstellungen

In den folgenden Listen 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 Anwendung, um das beste Verhältnis 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

• Das Festlegen von resolution für einzelne Inhalte ist nur bei Gemini 3-Modellen möglich.

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.