Veo 3 jest już dostępny w interfejsie Gemini API. Więcej informacji

Ta strona została przetłumaczona przez Cloud Translation API.

Rozpoznawanie filmów

Modele Gemini mogą przetwarzać filmy, co umożliwia wiele zaawansowanych zastosowań dla deweloperów, które w przeszłości wymagałyby modeli specyficznych dla danej domeny. Niektóre funkcje Gemini w zakresie widzenia obejmują:

Opisywanie, segmentowanie i wyodrębnianie informacji z filmów
Odpowiadanie na pytania dotyczące treści wideo
Odwoływanie się do konkretnych sygnatur czasowych w filmie

Gemini został zaprojektowany od podstaw jako model multimodalny i stale przesuwamy granice tego, co jest możliwe. Z tego przewodnika dowiesz się, jak używać interfejsu Gemini API do generowania odpowiedzi tekstowych na podstawie danych wejściowych wideo.

Wejście wideo

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

Prześlij plik wideo za pomocą interfejsu File API, zanim wyślesz żądanie do generateContent. Użyj tej metody w przypadku plików większych niż 20 MB, filmów trwających dłużej niż około 1 minutę lub gdy chcesz ponownie użyć pliku w wielu żądaniach.
Przekaż dane reklamy wideo w treści w żądaniu do generateContent. Używaj tej metody w przypadku mniejszych plików (poniżej 20 MB) i krótszych nagrań.
Dołącz adres URL z YouTube bezpośrednio do prompta.

Przesyłanie pliku wideo

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

Poniższy kod pobiera przykładowy film, przesyła go za pomocą interfejsu File API, czeka na jego przetworzenie, a następnie używa odwołania do pliku w żądaniu generateContent.

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

Przeczytaj

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

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

Przekazywanie danych wideo w treści

Zamiast przesyłać plik wideo za pomocą interfejsu File API, możesz przekazywać mniejsze filmy bezpośrednio w żądaniu do generateContent. Ta opcja jest odpowiednia 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

# 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

Uwzględnij adres URL z YouTube

Interfejs Gemini API i AI Studio obsługują adresy URL YouTube jako dane plikuPart. Możesz dołączyć adres URL YouTube do prompta z prośbą o podsumowanie, przetłumaczenie lub inne działanie związane z treścią filmu.

Ograniczenia:

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

Ten przykład pokazuje, jak uwzględnić adres URL YouTube z promptem:

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

Przeczytaj

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

Odwoływanie 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?" # 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.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?"

Transkrypcja filmu i dodawanie opisów wizualnych

Modele Gemini mogą transkrybować i opisywać wizualnie treści wideo, przetwarzając zarówno ścieżkę dźwiękową, jak i klatki wizualne. W przypadku opisów wizualnych model próbkuje film z częstotliwością 1 klatki na sekundę. Ta częstotliwość próbkowania może wpływać na poziom szczegółowości opisów, szczególnie w przypadku filmów z 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.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."

Dostosowywanie przetwarzania wideo

Możesz dostosować przetwarzanie wideo w interfejsie Gemini API, ustawiając interwały wycinania lub podając niestandardowe próbkowanie liczby klatek na sekundę.

Ustawianie interwałów przycinania

Możesz przyciąć film, określając videoMetadata z przesunięciem początku i końca.

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.')
        ]
    )
)

Ustawianie niestandardowej liczby klatek na sekundę

Możesz ustawić niestandardowe próbkowanie liczby klatek na sekundę, przekazując argument fps do funkcji videoMetadata.

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.')
        ]
    )
)

Domyślnie z filmu próbkowana jest 1 klatka na sekundę. W przypadku długich filmów możesz ustawić niską liczbę klatek na sekundę (< 1). Jest to szczególnie przydatne w przypadku filmów, które są w większości statyczne (np. wykładów). Jeśli chcesz rejestrować więcej szczegółów w szybko zmieniających się obrazach, rozważ ustawienie wyższej wartości FPS.

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 2.0 i 2.5 mogą przetwarzać dane wideo.
- Modele z oknem kontekstu o wielkości 2 milionów tokenów mogą przetwarzać filmy trwające do 2 godzin w domyślnej rozdzielczości lub do 6 godzin w niskiej rozdzielczości, a modele z oknem kontekstu o wielkości 1 miliona tokenów mogą przetwarzać filmy trwające do 1 godziny w domyślnej rozdzielczości lub do 3 godzin w niskiej rozdzielczości.
Przetwarzanie interfejsu API plików: w przypadku korzystania z interfejsu API plików filmy są próbkowane 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 kl./s):
  - Jeśli parametr mediaResolution ma wartość „low”, klatki są tokenizowane z szybkością 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 przy domyślnej rozdzielczości multimediów lub 100 tokenów na sekundę filmu przy niskiej rozdzielczości multimediów.
Format sygnatury czasowej: gdy w prompcie odwołujesz się do konkretnych momentów w filmie, używaj 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 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ć dane wyjściowe w postaci tekstu na podstawie danych wejściowych wideo. Więcej informacji znajdziesz w tych materiałach:

Instrukcje systemowe: instrukcje systemowe pozwalają sterować zachowaniem modelu na podstawie Twoich konkretnych potrzeb i przypadków użycia.
Interfejs Files API: dowiedz się więcej o przesyłaniu plików do wykorzystania w Gemini i zarządzaniu nimi.
Strategie promptowania plików: interfejs Gemini API obsługuje promptowanie za pomocą danych tekstowych, obrazów, dźwięku i wideo, czyli promptowanie multimodalne.
Wskazówki dotyczące bezpieczeństwa: modele generatywnej AI czasami tworzą 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.