Rozpoznawanie filmów

Modele Gemini mogą przetwarzać filmy, umożliwiając wielu deweloperom korzystanie z innowacyjnych zastosowań, które w przeszłości wymagały modeli w danej domenie. Gemini potrafi m.in.:

  • opisywać, dzielić na segmenty i wyodrębniać informacje z filmów o długości do 90 minut;
  • Odpowiedz na pytania dotyczące treści filmu
  • odwoływać się do konkretnych sygnatur czasowych w filmie,

Gemini został zaprojektowany od podstaw z myślą o multimodalności, a my wciąż przesuwamy granice tego, co możliwe. Z tego przewodnika dowiesz się, jak używać interfejsu Gemini API do generowania odpowiedzi tekstowych na podstawie filmów.

Zanim zaczniesz

Zanim wywołasz interfejs Gemini API, upewnij się, że masz zainstalowany wybrany pakiet SDK oraz skonfigurowany i gotowy do użycia klucz interfejsu Gemini API.

Wejście wideo

Filmy, które chcesz przetworzyć za pomocą Gemini, możesz przesłać na te sposoby:

Przesyłanie pliku wideo

Do przesyłania plików wideo możesz użyć interfejsu Files API. Zawsze używaj interfejsu Files API, gdy łączny rozmiar żądania (w tym pliku, promptu tekstowego, instrukcji systemowych itp.) przekracza 20 MB, czas trwania filmu jest znaczny lub zamierzasz używać tego samego filmu w kilku promptach.

Interfejs File API obsługuje bezpośrednio formaty plików wideo. W tym przykładzie użyto krótkiego filmu NASA „Jupiter's Great Red Spot Shrinks and Grows” (Wielka Czerwona Plama na Jowiszu kurczy się i powiększa). Źródło: Goddard Space Flight Center (GSFC)/David Ladd (2018).

Obraz „Jupiter's Great Red Spot Shrinks and Grows” jest w domenie publicznej i nie przedstawia osób, które można zidentyfikować. (wytyczne NASA dotyczące wykorzystania zdjęć i multimediów).

Podany niżej kod pobiera przykładowy film, przesyła go za pomocą interfejsu File API, czeka na jego przetworzenie, a potem używa odwołania do pliku w zapytaniu generateContent.

Python

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

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

response = client.models.generate_content(
    model="gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });

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.0-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();

Przeczytaj

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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

Więcej informacji o pracy z plikami multimedialnymi znajdziesz w artykule Interfejs Files API.

Przekazywanie danych wideo w ramach tekstu

Zamiast przesyłać plik wideo za pomocą interfejsu File API, możesz przekazać mniejsze filmy bezpośrednio w żądaniu do generateContent. Ta opcja jest odpowiednia w przypadku krótszych filmów o łącznym rozmiarze żądania poniżej 20 MB.

Oto przykład przekazywania danych wideo w ramach:

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.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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.0-flash:generateContent?key=$GOOGLE_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

Uwzględnij URL z YouTube

Interfejsy Gemini API i AI Studio obsługują adresy URL YouTube jako dane pliku Part. Możesz podać adres URL filmu w YouTube wraz z promptem, aby model streścił, przetłumaczył lub w inny sposób zmodyfikował zawartość filmu.

Ograniczenia:

  • Nie możesz przesłać więcej niż 8 godzin filmów w YouTube dziennie.
  • W przypadku każdego zgłoszenia możesz przesłać tylko 1 film.
  • Możesz przesyłać tylko filmy publiczne (nie prywatne ani niepubliczne).

Ten przykład pokazuje, jak uwzględnić adres URL filmu w YouTube z prośbą:

Python

response = client.models.generate_content(
    model='models/gemini-2.0-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());

Przeczytaj

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
  genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
  genai.Text("Please summarize the video in 3 sentences."))
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text.
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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

odwoływać się do sygnatur czasowych w treściach;

Możesz zadawać pytania dotyczące konkretnych punktów w filmie, używając sygnatur czasowych w formacie MM:SS.

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?";

Przeczytaj

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

Transkrypcja filmu i opisy wizualne

Modele Gemini mogą transkrybować i zapewniać wizualne opisy treści wideo, przetwarzając zarówno ścieżkę audio, jak i ramki wizualne. W przypadku opisów wizualnych model pobiera próbki z filmu z częstotliwością 1 klatka na sekundę. Ta częstotliwość próbkowania może wpływać na poziom szczegółowości w opisach, zwłaszcza w przypadku filmów z bardzo szybko zmieniającymi się obrazami.

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.";

Przeczytaj

    prompt := []genai.Part{
        genai.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
        genai.Text("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."

Obsługiwane formaty wideo

Gemini obsługuje te typy MIME formatu wideo:

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

Szczegóły techniczne dotyczące filmów

  • Obsługiwane modele i kontekst: wszystkie modele Gemini 2.0 i 2.5 mogą przetwarzać dane wideo.
    • Modele z oknem kontekstu o wielkości 2 mln tokenów mogą przetwarzać filmy o długości do 2 godzin, a modele z oknem kontekstu o wielkości 1 mln tokenów mogą przetwarzać filmy o długości do 1 godziny.
  • Przetwarzanie interfejsu File API: gdy używasz interfejsu File API, filmy są próbkowane z szybkością 1 klatki na sekundę (FPS), a dźwięk jest przetwarzany z szybkością 1 Kbps (jeden kanał). Czas jest dodawany co sekundę.
    • Te stawki mogą ulec zmianie w przyszłości, aby poprawić jakość wnioskowania.
  • Obliczanie tokenów: każda sekunda filmu jest tokenizowana w ten sposób:
    • Pojedyncze klatki (próbkowane z częstotliwością 1 FPS): 258 tokenów na klatkę.
    • Dźwięk: 32 tokeny na sekundę.
    • Zawiera on metadane.
    • Łącznie: około 300 tokenów na sekundę filmu.
  • Format sygnatury czasowej: jeśli w promptach odwołujesz się do konkretnych momentów w filmie, użyj formatu MM:SS (np. 01:15 przez 1 minutę i 15 sekund).
  • Sprawdzone metody:
    • Aby uzyskać optymalne wyniki, używaj tylko 1 filmu na żądanie prompta.
    • Jeśli łączysz tekst z jednym filmem, umieść prompt tekstowy po części wideo w tablicy contents.
    • Pamiętaj, że szybkie sekwencje akcji mogą stracić na jakości ze względu na częstotliwość próbkowania 1 FPS. W razie potrzeby możesz spowolnić takie klipy.

Co dalej?

Z tego przewodnika dowiesz się, jak przesyłać pliki wideo i generować tekst na podstawie filmów wejściowych. Więcej informacji znajdziesz w tych materiałach:

  • Instrukcje systemowe: instrukcje systemowe umożliwiają kierowanie działaniem modelu na podstawie konkretnych potrzeb i przypadków użycia.
  • Files API: dowiedz się więcej o przesyłaniu plików i zarządzaniu nimi w Gemini.
  • Strategie wyświetlania promptów dotyczących plików: interfejs Gemini API obsługuje prompty z tekstem, obrazem, dźwiękiem i danymi wideo, które są też nazywane promptami multimodalnymi.
  • Wskazówki dotyczące bezpieczeństwa: modele generatywnej AI czasami generują nieoczekiwane wyniki, np. niedokładne, stronnicze lub obraźliwe. Przetwarzanie końcowe i sprawdzanie przez weryfikatorów są niezbędne do ograniczenia ryzyka szkód wynikających z takich danych wyjściowych.