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 Qualität der Antwort gegen Latenz und Kosten abwägen. Bei visuellen Eingaben und Dokumenteingaben wird die Tokenzuweisung basierend auf der Auflösungseinstellung skaliert. Bei Audioeingaben werden Tokens 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 können die Media-Auflösung für einzelne Media-Objekte (Inhaltselemente) in Ihrer Anfrage konfigurieren (Gemini 4- und Gemini 3-Modelle).

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

Mit den Gemini 4- und Gemini 3-Modellen 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 Auflösungsstufen in einer einzelnen Anfrage kombinieren. Beispielsweise können Sie eine hohe Auflösung für ein komplexes Diagramm und eine niedrige Auflösung für ein einfaches Kontextbild 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(""));

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

Verfügbare Auflösungswerte

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

• unspecified: Die Standardeinstellung. Die Tokenanzahl für diese Stufe variiert erheblich zwischen Gemini 4/3 und früheren Gemini-Modellen.
• low: Geringere Tokenanzahl, was zu einer schnelleren Verarbeitung und niedrigeren Kosten führt, aber weniger Details bietet.
• medium: Ein ausgewogenes Verhältnis zwischen Detailgenauigkeit, Kosten und Latenz.
• high: Höhere Tokenanzahl, die mehr Details für das Modell bietet, aber zu einer höheren Latenz und höheren Kosten führt.
• ultra_high (nur pro Inhaltselement): Höchste Tokenanzahl, die für bestimmte Anwendungsfälle wie die Computernutzung erforderlich ist.

Beachten Sie, dass 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 4- und Gemini 3-Modelle

Die richtige Auflösung auswählen

• Standard (unspecified): Beginnen Sie mit der Standardeinstellung. Sie ist für ein gutes Gleichgewicht zwischen Qualität, Latenz und Kosten für die meisten gängigen Anwendungsfälle optimiert.
• low: Verwenden Sie diese Einstellung für Szenarien, in denen Kosten und Latenz entscheidend sind und detaillierte Informationen 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 Inhaltselement verfügbar. Empfohlen für bestimmte Anwendungsfälle wie die Computernutzung oder wenn Tests eine deutliche Verbesserung gegenüber high zeigen.
• Steuerung pro Inhaltselement (Gemini 4 und 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 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 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

• Das Festlegen der resolution für einzelne Inhaltselemente wird in 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.