Videoinhalte erkennen

Gemini-Modelle können Videos verarbeiten und ermöglichen so viele innovative Entwickler-Anwendungsfälle, für die früher domänenspezifische Modelle erforderlich gewesen wären. Gemini kann unter anderem Folgendes:

  • Videos beschreiben, segmentieren und Informationen aus Videos extrahieren
  • Fragen zu Videoinhalten beantworten
  • Auf bestimmte Zeitstempel in einem Video verweisen

Gemini wurde von Grund auf multimodal entwickelt und wir erweitern die Grenzen des Möglichen kontinuierlich. In diesem Leitfaden wird gezeigt, wie Sie mit der Gemini API Textantworten basierend auf Videoeingaben generieren.

Videoeingang

Sie haben folgende Möglichkeiten, Videos als Eingabe für Gemini bereitzustellen:

  • Laden Sie eine Videodatei mit der File API hoch, bevor Sie eine Anfrage an generateContent senden. Verwenden Sie diese Methode für Dateien, die größer als 20 MB sind, für Videos, die länger als etwa 1 Minute sind, oder wenn Sie die Datei für mehrere Anfragen wiederverwenden möchten.
  • Inline-Videodaten mit der Anfrage an generateContent übergeben. Verwenden Sie diese Methode für kleinere Dateien (unter 20 MB) und kürzere Zeiträume.
  • YouTube-URL direkt in den Prompt einfügen

Videodatei hochladen

Sie können die Files API verwenden, um eine Videodatei hochzuladen. Verwenden Sie immer die Files API, wenn die Gesamtgröße der Anfrage (einschließlich Datei, Text-Prompt, Systemanweisungen usw.) mehr als 20 MB beträgt, die Videodauer lang ist oder Sie dasselbe Video in mehreren Prompts verwenden möchten. Die File API akzeptiert Videodateiformate direkt.

Im folgenden Codebeispiel wird das Beispielvideo heruntergeladen, mit der File API hochgeladen, auf die Verarbeitung gewartet und dann die Dateireferenz in einer generateContent-Anfrage verwendet.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} 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" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

Ok

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", nil)

parts := []*genai.Part{
    genai.NewPartFromText("Summarize this video. Then create a quiz with an answer key based on the information in this video."),
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-2.5-flash",
    contents,
    nil,
)

fmt.Println(result.Text())

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)
echo file_uri=$file_uri

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

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"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 -r ".candidates[].content.parts[].text" response.json

Weitere Informationen zum Arbeiten mit Media-Dateien finden Sie unter Files API.

Videodaten inline übergeben

Anstatt eine Videodatei über die File API hochzuladen, können Sie kleinere Videos direkt in der Anfrage an generateContent übergeben. Diese Methode eignet sich für kürzere Videos mit einer Gesamtanfragegröße von unter 20 MB.

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

Python

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

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 contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: contents,
});
console.log(response.text);

REST

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"video/mp4",
                "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'"
              }
            },
            {"text": "Please summarize the video in 3 sentences."}
        ]
      }]
    }' 2> /dev/null

YouTube-URL einfügen

Die Gemini API und AI Studio unterstützen YouTube-URLs als Part-Datei. Sie können eine YouTube-URL in einen Prompt einfügen, in dem das Modell aufgefordert wird, die Videoinhalte zusammenzufassen, zu übersetzen oder auf andere Weise mit ihnen zu interagieren.

Beschränkungen:

  • In der kostenlosen Version können Sie pro Tag maximal 8 Stunden YouTube-Videos hochladen.
  • Bei der kostenpflichtigen Stufe gibt es keine Begrenzung der Videolänge.
  • Bei Modellen vor Version 2.5 können Sie nur ein Video pro Anfrage hochladen. Bei Modellen nach Version 2.5 können Sie pro Anfrage maximal 10 Videos hochladen.
  • Du kannst nur öffentliche Videos hochladen, keine privaten oder nicht gelisteten Videos.

Im folgenden Beispiel sehen Sie, wie Sie eine YouTube-URL in einen Prompt einfügen:

Python

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.response.text());

Ok

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  parts := []*genai.Part{
      genai.NewPartFromText("Please summarize the video in 3 sentences."),
      genai.NewPartFromURI("https://www.youtube.com/watch?v=9hE5-98ZeCg","video/mp4"),
  }

  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {"text": "Please summarize the video in 3 sentences."},
            {
              "file_data": {
                "file_uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
              }
            }
        ]
      }]
    }' 2> /dev/null

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?" # Adjusted timestamps for the NASA video

JavaScript

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

Ok

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("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?"

Video transkribieren und visuelle Beschreibungen bereitstellen

Die Gemini-Modelle können Videoinhalte transkribieren und visuell beschreiben, indem sie sowohl den Audiotrack als auch die visuellen Frames verarbeiten. Für visuelle Beschreibungen wird das Video mit einer Rate von 1 Frame pro Sekunde gesampelt. Diese Samplingrate kann sich auf den Detaillierungsgrad der Beschreibungen auswirken, insbesondere bei Videos mit sich schnell ändernden Bildern.

Python

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Ok

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

REST

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

Videoverarbeitung anpassen

Sie können die Videoverarbeitung in der Gemini API anpassen, indem Sie Clipping-Intervalle festlegen oder benutzerdefiniertes Sampling der Frame-Rate bereitstellen.

Ausschnittintervalle festlegen

Sie können Videos zuschneiden, indem Sie videoMetadata mit Start- und End-Offsets angeben.

Python

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

Benutzerdefinierte Bildrate festlegen

Sie können die benutzerdefinierte Framerate-Erfassung festlegen, indem Sie ein fps-Argument an videoMetadata übergeben.

Python

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

Standardmäßig wird aus dem Video ein Frame pro Sekunde (FPS) ausgewählt. Bei langen Videos empfiehlt es sich, eine niedrige Framerate (< 1) festzulegen. Das ist besonders nützlich für Videos, die größtenteils statisch sind, z.B. Vorträge. Wenn Sie mehr Details in sich schnell ändernden Bildern erfassen möchten, sollten Sie einen höheren FPS-Wert festlegen.

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 2.0- und 2.5-Modelle können Videodaten verarbeiten.
    • Modelle mit einem Kontextfenster von 2 Millionen Tokens können Videos mit einer Länge von bis zu 2 Stunden in der Standardauflösung oder bis zu 6 Stunden in niedriger Auflösung verarbeiten. Modelle mit einem Kontextfenster von 1 Million Tokens können Videos mit einer Länge von bis zu 1 Stunde in der Standardauflösung oder bis zu 3 Stunden in niedriger Auflösung verarbeiten.
  • Verarbeitung über die File API: Bei Verwendung der File API werden Videos mit 1 Frame pro Sekunde (FPS) gesampelt 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 des Videos wird so tokenisiert:
    • Einzelne Frames (mit 1 FPS):
      • Wenn mediaResolution auf „Niedrig“ festgelegt 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.
    • Insgesamt: ca. 300 Tokens pro Sekunde Video bei Standardauflösung oder 100 Tokens pro Sekunde Video bei niedriger Auflösung.
  • Zeitstempelformat: Wenn du in deinem Prompt auf bestimmte Momente in einem Video verweist, verwende das Format MM:SS (z.B. 01:15 für 1 Minute und 15 Sekunden).
  • Best Practices:
    • Verwenden Sie für optimale Ergebnisse nur ein Video pro Aufforderung.
    • Wenn Sie Text und ein einzelnes Video kombinieren, platzieren Sie den Text-Prompt im contents-Array nach dem Videoteil.
    • Beachten Sie, dass bei schnellen Aktionssequenzen aufgrund der Abtastrate von 1 Bild pro Sekunde Details verloren gehen können. Verlangsame solche Clips bei Bedarf.

Nächste Schritte

In diesem Leitfaden wird beschrieben, wie Sie Videodateien hochladen und Textausgaben aus Videoeingaben generieren. Weitere Informationen finden Sie in den folgenden Ressourcen:

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