Rozpoznawanie filmów

Więcej informacji o generowaniu filmów znajdziesz w przewodniku Veo.

Modele Gemini mogą przetwarzać filmy, co umożliwia wiele zaawansowanych zastosowań dla deweloperów, które wcześniej wymagałyby modeli specyficznych dla danej domeny. Niektóre funkcje Gemini związane z widzeniem obejmują możliwość opisywania, segmentowania i wyodrębniania informacji z filmów, odpowiadania na pytania dotyczące treści filmów oraz odwoływania się do konkretnych sygnatur czasowych w filmie.

Filmy możesz przekazywać do Gemini na te sposoby:

Sposób wprowadzania tekstu Wielkość maksymalna Zalecany przypadek użycia
File API 20 GB (płatne) / 2 GB (bezpłatne) Duże pliki (powyżej 100 MB), długie filmy (powyżej 10 minut), pliki wielokrotnego użytku.
Rejestracja Cloud Storage 2 GB (na plik, bez limitów miejsca na dane) Duże pliki (powyżej 100 MB), długie filmy (powyżej 10 minut), trwałe pliki wielokrotnego użytku.
Dane w treści < 100 MB Małe pliki (<100 MB), krótki czas trwania (<1 min), jednorazowe dane wejściowe.
Adresy URL w YouTube Nie dotyczy publiczne filmy w YouTube,

Uwaga: w większości przypadków zalecamy używanie interfejsu File API, zwłaszcza w przypadku plików większych niż 100 MB lub gdy chcesz użyć pliku w wielu żądaniach.

Więcej informacji o innych metodach wprowadzania plików, np. za pomocą zewnętrznych adresów URL lub plików przechowywanych w Google Cloud, znajdziesz w przewodniku Metody wprowadzania plików.

Przesyłanie pliku wideo

Poniższy kod pobiera przykładowy film, przesyła go za pomocą interfejsu Files API, czeka na jego przetworzenie, a następnie używa odniesienia do przesłanego pliku, aby podsumować film.

Python

from google import genai
import base64

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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.steps[-1].content[0].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 interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      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(interaction.steps.at(-1).content[0].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)
echo file_uri=$file_uri

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

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-flash-preview",
      "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

Zawsze używaj interfejsu Files API, gdy łączny rozmiar żądania (w tym pliku, tekstu prompta, instrukcji systemowych itp.) jest większy niż 20 MB, czas trwania filmu jest długi lub jeśli zamierzasz użyć tego samego filmu w wielu promptach. Interfejs File API akceptuje bezpośrednio formaty plików wideo.

Więcej informacji o pracy z plikami multimedialnymi znajdziesz w interfejsie API plików.

Przekazywanie danych wideo w tekście

Zamiast przesyłać plik wideo za pomocą interfejsu File API, możesz przekazywać mniejsze filmy bezpośrednio w żądaniu. Jest to odpowiednie rozwiązanie w przypadku krótszych filmów, których łączny rozmiar żądania nie przekracza 20 MB.

Oto przykład podawania danych o filmie w tekście:

Python

from google import genai

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-flash-preview',
    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.steps[-1].content[0].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-flash-preview",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.steps.at(-1).content[0].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-flash-preview",
      "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

Przekazywanie adresów URL z YouTube

Możesz przekazywać adresy URL YouTube bezpośrednio do interfejsu Gemini API w ramach żądania w ten sposób:

Python

from google import genai

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

JavaScript

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3-flash-preview",
  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.steps.at(-1).content[0].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-flash-preview",
      "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

Ograniczenia:

  • W przypadku bezpłatnej wersji nie możesz przesyłać więcej niż 8 godzin filmów na YouTube dziennie.
  • W przypadku wersji płatnej nie ma limitu długości filmu.
  • W przypadku modeli starszych niż Gemini 2.5 możesz przesłać tylko 1 film na prośbę. W przypadku modeli Gemini 2.5 i nowszych możesz przesłać maksymalnie 10 filmów na żądanie.
  • Możesz przesyłać tylko filmy publiczne (nie prywatne ani niepubliczne).

Odwołuj się do sygnatur czasowych w treści

Możesz zadawać pytania dotyczące konkretnych momentó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?"

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

Wyodrębnianie szczegółowych informacji z filmu

Modele Gemini oferują zaawansowane funkcje rozumienia treści wideo poprzez przetwarzanie informacji z ścieżek audio i wizualnych. Dzięki temu możesz wyodrębniać wiele szczegółów, w tym generować opisy tego, co dzieje się w filmie, i odpowiadać na pytania dotyczące jego treści.

W przypadku opisów wizualnych model próbkuje film z szybkością 1 klatki na sekundę (FPS). Ta domyślna częstotliwość próbkowania sprawdza się w przypadku większości treści, ale może nie wychwytywać szczegółów w filmach z szybkim ruchem lub szybkimi zmianami scen. W przypadku takich treści o dużej dynamice rozważ ustawienie niestandardowej liczby klatek na sekundę.

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

Obsługiwane formaty wideo

Gemini obsługuje te typy MIME formatów 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 mogą przetwarzać dane wideo.
    • Modele z oknem kontekstu o wielkości 1 M tokenów mogą przetwarzać filmy o długości do 1 godziny w domyślnej rozdzielczości lub do 3 godzin w niskiej rozdzielczości.
  • Przetwarzanie za pomocą interfejsu File API: w przypadku korzystania z interfejsu File API filmy są przechowywane z częstotliwością 1 klatki na sekundę, a dźwięk jest przetwarzany z szybkością 1 kbps (jeden kanał). Sygnatury czasowe są dodawane co sekundę.
    • W przyszłości te stawki mogą ulec zmianie w związku z ulepszaniem wnioskowania.
  • Obliczanie tokenów: każda sekunda filmu jest tokenizowana w ten sposób:
    • Pojedyncze klatki (próbkowane z częstotliwością 1 klatki na sekundę):
      • Jeśli parametr media_resolution ma wartość „niska”, klatki są tokenizowane przy użyciu 66 tokenów na klatkę.
      • W przeciwnym razie klatki są tokenizowane z szybkością 258 tokenów na klatkę.
    • Audio: 32 tokeny na sekundę.
    • Zawiera też metadane.
    • Łącznie: około 300 tokenów na sekundę filmu w domyślnej rozdzielczości multimediów lub 100 tokenów na sekundę filmu w niskiej rozdzielczości multimediów.
  • Rozdzielczość multimediów: Gemini 3 wprowadza szczegółową kontrolę nad przetwarzaniem multimodalnym za pomocą parametru media_resolution. Parametr media_resolution określa maksymalną liczbę tokenów przydzielonych na obraz wejściowy lub klatkę filmu. Wyższe rozdzielczości zwiększają zdolność modelu do odczytywania drobnego tekstu lub identyfikowania małych szczegółów, ale zwiększają zużycie tokenów i opóźnienia.

    obliczeń znajdziesz w przewodniku po tokenach.

  • Format sygnatury czasowej: gdy w prompcie odwołujesz się do konkretnych momentów w filmie, używaj formatu MM:SS (np. 01:15 w przypadku 1 minuty 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 filmu w tablicy input.
    • Pamiętaj, że szybkie sekwencje działań mogą utracić szczegóły ze względu na częstotliwość próbkowania wynoszącą 1 klatkę na sekundę. W razie potrzeby możesz spowolnić takie klipy.

Co dalej?

Z tego przewodnika dowiesz się, jak przesyłać pliki wideo i generować z nich tekst. Więcej informacji znajdziesz w tych materiałach:

  • Instrukcje systemowe: instrukcje systemowe pozwalają sterować zachowaniem modelu na podstawie konkretnych potrzeb i przypadków użycia.
  • Interfejs Files API: dowiedz się więcej o przesyłaniu plików i zarządzaniu nimi na potrzeby Gemini.
  • Strategie tworzenia promptów z plikami: interfejs Gemini API obsługuje tworzenie promptów za pomocą danych tekstowych, obrazów, dźwięku i wideo, czyli tworzenie promptów multimodalnych.
  • Wskazówki dotyczące bezpieczeństwa: modele generatywnej AI czasami generują nieoczekiwane wyniki, np. niedokładne, stronnicze lub obraźliwe. Przetwarzanie końcowe i ocena przez człowieka są niezbędne, aby ograniczyć ryzyko szkód wynikających z takich danych wyjściowych.