Videos verstehen

Informationen zur Videogenerierung finden Sie in der Veo Anleitung.

Gemini-Modelle können Videos verarbeiten und so viele neue Anwendungsfälle für Entwickler ermöglichen, für die in der Vergangenheit domänenspezifische Modelle erforderlich gewesen wären. Zu den Vision-Funktionen von Gemini gehören unter anderem die Möglichkeit, Videos zu beschreiben, zu segmentieren und Informationen daraus zu extrahieren, Fragen zu Videoinhalten zu beantworten und auf bestimmte Zeitstempel in einem Video zu verweisen.

Sie können Videos auf folgende Weise als Eingabe für Gemini bereitstellen:

Eingabemethode Max. Größe Empfohlener Anwendungsfall
File API 20 GB (kostenpflichtig) / 2 GB (kostenlos) Große Dateien (über 100 MB), lange Videos (über 10 Minuten), wiederverwendbare Dateien.
Cloud Storage-Registrierung 2 GB (pro Datei, keine Speicherlimits) Große Dateien (über 100 MB), lange Videos (über 10 Minuten), persistente, wiederverwendbare Dateien.
Inlinedaten Unter 100 MB Kleine Dateien (unter 100 MB), kurze Dauer (unter 1 Minute), einmalige Eingaben.
YouTube-URLs Öffentliche YouTube-Videos.

Hinweis: Die File API wird für die meisten Anwendungsfälle empfohlen, insbesondere für Dateien, die größer als 100 MB sind, oder wenn Sie die Datei in mehreren Anfragen wiederverwenden möchten.

Informationen zu anderen Methoden für die Dateieingabe, z. B. die Verwendung externer URLs oder in Google Cloud gespeicherter Dateien, finden Sie in der Anleitung zu Methoden für die Dateieingabe.

Videodatei hochladen

Mit dem folgenden Code wird ein Beispielvideo heruntergeladen, mit der Files API, hochgeladen, auf die Verarbeitung gewartet und dann die hochgeladene Dateireferenz verwendet, um das Video zusammenzufassen.

Python

from google import genai
import base64
import time

client = genai.Client()

myfile = client.files.upload(file="path/to/sample.mp4")

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
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.5-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
      ]
    }' 2> /dev/null > response.json

jq ".steps[].content[0].text" response.json

Verwenden Sie immer die Files API, wenn die Gesamtgröße der Anfrage (einschließlich Datei, Text-Prompt, Systemanweisungen usw.) größer als 20 MB ist, die Videodauer erheblich ist oder wenn Sie dasselbe Video in mehreren Prompts verwenden möchten. Die File API akzeptiert Videodateiformate direkt.

Weitere Informationen zum Arbeiten mit Mediendateien finden Sie unter Files API.

Videodaten inline übergeben

Anstatt eine Videodatei mit der File API hochzuladen, können Sie kleinere Videos direkt in der Anfrage übergeben. Dies eignet sich für kürzere Videos mit einer Gesamtgröße der Anfrage von unter 20 MB.

Hier ein Beispiel für die Bereitstellung von Inline-Videodaten:

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.5-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const interaction = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

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.5-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null

YouTube-URLs übergeben

Sie können YouTube-URLs direkt als Teil Ihrer Anfrage an die Gemini API übergeben:

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.5-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

REST

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.5-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
      ]
    }' 2> /dev/null

Beschränkungen :

  • Im kostenlosen Abo können Sie pro Tag maximal 8 Stunden YouTube-Video hochladen.
  • Im kostenpflichtigen Abo gibt es keine Beschränkung basierend auf der Videolänge.
  • Bei Modellen vor Gemini 2.5 können Sie nur ein Video pro Anfrage hochladen. Bei Gemini 2.5 und neueren Modellen können Sie maximal 10 Videos pro Anfrage hochladen.
  • Sie können nur öffentliche Videos hochladen (keine privaten oder nicht gelisteten Videos).

Auf Zeitstempel im Inhalt verweisen

Sie können Fragen zu bestimmten Zeitpunkten im Video stellen, indem Sie Zeitstempel im Format MM:SS verwenden.

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?"

JavaScript

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

REST

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

Detaillierte Erkenntnisse aus Videos extrahieren

Gemini-Modelle bieten leistungsstarke Funktionen zum Verstehen von Videoinhalten, indem sie Informationen aus den Audio- und visuellen Streams verarbeiten. So können Sie eine Vielzahl von Details extrahieren, einschließlich Beschreibungen dessen, was in einem Video passiert, und Antworten auf Fragen zu den Inhalten.

Für visuelle Beschreibungen nimmt das Modell das Video mit einer Rate von 1 Frame pro Sekunde (FPS) auf. Diese Standard-Samplingrate eignet sich gut für die meisten Inhalte, aber es ist möglich, dass Details in Videos mit schnellen Bewegungen oder schnellen Szenenwechseln verloren gehen.

Python

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Unterstützte Videoformate

Gemini unterstützt die folgenden MIME-Typen für Videoformate:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

Technische Details zu Videos

  • Unterstützte Modelle und Kontext: Alle Gemini-Modelle können Videodaten verarbeiten.
    • Modelle mit einem Kontextfenster von 1 Million können Videos mit einer Länge von bis zu 1 Stunde bei Standard-Mediaauflösung oder 3 Stunden bei niedriger Mediaauflösung verarbeiten.
  • Verarbeitung mit der File API: Bei Verwendung der File API werden Videos mit 1 FPS gespeichert und Audio mit 1 kbit/s (Einzelkanal) verarbeitet. Zeitstempel werden jede Sekunde hinzugefügt.
    • Diese Raten können sich in Zukunft ändern, um die Inferenz zu verbessern.
  • Tokenberechnung: Jede Sekunde Video wird so tokenisiert:
    • Einzelne Frames (mit 1 FPS aufgenommen):
      • Wenn media_resolution auf „low“ gesetzt ist, werden Frames mit 66 Tokens pro Frame tokenisiert.
      • Andernfalls werden Frames mit 258 Tokens pro Frame tokenisiert.
    • Audio: 32 Tokens pro Sekunde.
    • Metadaten sind ebenfalls enthalten.
    • Gesamt: Ungefähr 300 Tokens pro Sekunde Video bei Standard-Mediaauflösung oder 100 Tokens pro Sekunde Video bei niedriger Mediaauflösung.
  • Mediaauflösung: Mit Gemini 3 wird mit dem Parameter media_resolution eine detaillierte Steuerung der multimodalen Vision-Verarbeitung eingeführt. Der Parameter media_resolution bestimmt die maximale Anzahl von Tokens, die pro Eingabebild oder Video-Frame zugewiesen werden. Höhere Auflösungen verbessern die Fähigkeit des Modells, kleinen Text zu lesen oder kleine Details zu erkennen, erhöhen aber die Tokennutzung und die Latenz.

    Weitere Informationen zur Tokenberechnung finden Sie in der Anleitung zu Tokens.

  • Zeitstempelformat: Wenn Sie in Ihrem Prompt auf bestimmte Momente in einem Video verweisen, verwenden Sie das MM:SS Format (z.B. 01:15 für 1 Minute und 15 Sekunden).

  • Best Practices:

    • Verwenden Sie für optimale Ergebnisse nur ein Video pro Prompt-Anfrage.
    • Wenn Sie Text und ein einzelnes Video kombinieren, platzieren Sie den Text-Prompt nach dem Videoteil im input-Array.
    • Schnelle Actionsequenzen können aufgrund der Samplingrate von 1 FPS Details verlieren. Verlangsamen Sie solche Clips gegebenenfalls.

Nächste Schritte

In dieser Anleitung wird gezeigt, wie Sie Videodateien hochladen und Textausgaben aus Videoeingaben generieren. Weitere Informationen finden Sie in folgenden Dokumenten:

  • Systemanweisungen: Mit Systemanweisungen können Sie das Verhalten des Modells entsprechend Ihren spezifischen Anforderungen und Anwendungsfällen steuern.
  • Files API: Weitere Informationen zum Hochladen und Verwalten von Dateien für die Verwendung mit Gemini.
  • Strategien für Prompts mit Dateien: Die Gemini API unterstützt Prompts mit Text-, Bild-, Audio- und Videodaten, auch multimodale Prompts genannt.
  • Sicherheitshinweise: Generative KI-Modelle liefern manchmal unerwartete Ausgaben, z. B. Ausgaben, die falsch, voreingenommen oder anstößig sind. Nachbearbeitung und menschliche Bewertung sind unerlässlich, um das Risiko von Schäden durch solche Ausgaben zu begrenzen.