Rozpoznawanie filmów

Więcej informacji o generowaniu filmów znajdziesz w przewodniku Gemini Omni Flash.

Modele Gemini mogą przetwarzać filmy, co umożliwia wiele zaawansowanych zastosowań dla deweloperów, które w przeszłości wymagałyby modeli specjalistycznych. 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 znaczników czasu 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 do ponownego wykorzystania.
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 korzystanie z 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 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.8-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.8-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();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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

Aby zoptymalizować wydajność i skuteczność tokenów, rozważ użycie przetwarzania wideo opartego na agentach.

Zawsze używaj interfejsu Files API, gdy łączny rozmiar żądania (w tym pliku, promptu tekstowego, 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 Files API.

Przekazywanie danych o filmie w tekście

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

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.8-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.8-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);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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

Przekazywanie adresów URL z YouTube

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

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-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.8-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);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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

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 wideo.
  • 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 (a nie prywatne ani niepubliczne).

Analizowanie filmów przez agenta

Domyślnie dane wejściowe wideo wykorzystują przetwarzanie statyczne (wyodrębnianie klatek z częstotliwością 1 klatki na sekundę). Modele Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash i 3.5 Flash Lite obsługują też agentowe rozumienie filmów, w którym model dynamicznie eksploruje oś czasu filmu, selektywnie analizuje transkrypcje i na bieżąco dostosowuje liczbę klatek na sekundę oraz rozdzielczość na podstawie promptu.

Tryb Opis Obsługiwane modele
Statyczny (domyślnie) Wyodrębnia klatki ze stałą częstotliwością (1 klatka na sekundę) i umieszcza je w kontekście w jednym przebiegu. Sprawdza się w przypadku krótkich klipów. Wszystkie modele Gemini
Agentic Model dynamicznie porusza się po osi czasu filmu, wczytując tylko te treści, których potrzebuje na podstawie promptu. Do 88% większa wydajność tokenów i o ok. 7% wyższa jakość w przypadku długich treści. Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

Wybierz tryb przetwarzania

Ogólnie rzecz biorąc, zacznij od trybu agentowego, zwłaszcza jeśli optymalizujesz jakość odpowiedzi lub wydajność tokenów.

  • Agentic: długie filmy lub zapytania dotyczące konkretnych momentów. Model dynamicznie porusza się po osi czasu, aby wyszukiwać informacje istotne w danym kontekście, nie wypełniając okna kontekstu.
  • Statyczne: zapytania wrażliwe na opóźnienia w przypadku krótkich klipów (poniżej 5 minut) lub przypadki, w których wymagana jest precyzja na poziomie klatek w całym klipie.

Uwaga: w przypadku długich filmów lub złożonych promptów, w których przetwarzanie przez agenta zajmuje więcej czasu, używaj przesyłania strumieniowego (stream=True) lub wykonywania w tle (background=True). Dzięki temu połączenie pozostanie aktywne, pojawią się pośrednie etapy rozumowania i unikniesz przekroczenia limitu czasu połączenia lub uwierzytelniania.

Ustaw tryb przetwarzania

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
video_file = client.files.upload(file="path/to/lecture.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = client.files.get(name=video_file.name)

# Use agentic processing
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

// Upload a long video
let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" }
});

while (videoFile.state === "PROCESSING") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name });
}

// Use agentic processing
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ]
});
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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ]
  }' 2> /dev/null

Uwaga: aby sprawdzić, czy użyto przetwarzania z udziałem agenta, sprawdź interaction.steps. Obecność symboli processing_call i processing_result oznacza, że model dynamicznie poruszał się po filmie.

Etapy odpowiedzi

Przetwarzanie agentowe dodaje do tablicy steps 2 nowe typy kroków:

  • processing_call: model poprosił o segment filmu lub transkrypcję dźwięku, zidentyfikowane przez id.
  • processing_result: wynik tego wczytania, połączony przez call_id.

Pojawiają się one na przemian z krokami thought (gdy włączone są podsumowania) i poprzedzają ostatni krok model_output. Można ich używać do wyświetlania ścieżki postępu w interfejsie, ale nie wymagają one odpowiedzi.

Poniższy przykład pokazuje ładunek odpowiedzi z przeplatanymi krokami przetwarzania:

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

Mieszanie trybów przetwarzania w różnych filmach

W ramach tego samego żądania możesz ustawić różne tryby przetwarzania dla poszczególnych filmów:

Python

from google import genai

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" }
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" }
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ]
});
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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
  }' 2> /dev/null

Rozmowy wideo wieloetapowe

Kontekst filmu jest zachowywany w kolejnych turach rozmowy. W przypadku przetwarzania z użyciem agentów:

  • Tryb stanowy (z użyciem previous_interaction_id): serwer zachowuje kontekst filmu. Nie musisz niczego dodatkowo robić.
  • Tryb bezstanowy (z użyciem step_list): w trybie bezstanowym odpowiedź zawiera kroki processing_call i processing_result, które kodują kontekst filmu. Aby zachować kontekst filmu, w kolejnej prośbiestep_list musisz uwzględnić wszystkie kroki z odpowiedzi. Chociaż ich pominięcie nie powoduje obecnie błędu interfejsu API, kontekst filmu zostaje utracony, co znacznie obniża jakość odpowiedzi na kolejne pytania. Pamiętaj, że zwrócone kroki wysłane w kolejnych żądaniach są uwzględniane w liczbie tokenów wejściowych.

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

Java

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

Go

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, przetwarzając informacje z ścieżek audio i wizualnych. Dzięki temu możesz wyodrębnić 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.

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

Java

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

Go

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

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ę. Te opcje dostosowywania są obsługiwane tylko podczas przetwarzania filmu w trybie "static".

Ustawianie interwałów przycinania

Możesz przyciąć film, określając parametry start_offset i end_offset w obiekcie konfiguracji processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

Ustawianie niestandardowej liczby klatek na sekundę

Możesz ustawić niestandardowe próbkowanie liczby klatek na sekundę, przekazując argument fps w obiekcie konfiguracji processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

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 miliona tokenów mogą domyślnie przetwarzać filmy o długości do 3 godzin (w niskiej rozdzielczości) lub do 1 godziny (w wysokiej rozdzielczości).
  • Tryby przetwarzania: modele Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite i nowsze obsługują 2 tryby przetwarzania filmów:
    • Statyczne: klatki są wyodrębniane z częstotliwością 1 klatki na sekundę i umieszczane w kontekście (domyślnie dla wszystkich modeli). Dźwięk jest przetwarzany z szybkością 1 kb/s (jeden kanał). Sygnatury czasowe są dodawane co sekundę. Najlepszy w przypadku krótkich klipów lub gdy liczy się każda klatka (np. podczas sprawdzania klatka po klatce). Pamiętaj, że szybkie sekwencje akcji mogą utracić szczegóły ze względu na częstotliwość próbkowania 1 klatki na sekundę.
    • Aktywny: model dynamicznie porusza się po filmie, wczytując na żądanie transkrypcję, klatki lub dźwięk. W przypadku długich treści zużywa do 88% mniej tokenów, chociaż nawigacja może nieznacznie wydłużyć czas do pierwszego tokena (TTFT) w przypadku krótkich klipów (poniżej 5 minut) ze względu na wewnętrzne rozumowanie i wymianę informacji z narzędziami przed rozpoczęciem generowania. Najlepszy w przypadku długich filmów, ponieważ pozwala optymalizować koszty tokenów i jakość odpowiedzi. Obsługiwane w przypadku modeli Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash i 3.5 Flash Lite. Więcej informacji znajdziesz w sekcji Analizowanie filmów przez agenta.
  • Obliczanie tokenów (tryb statyczny): każda sekunda filmu jest tokenizowana w ten sposób:
    • Pojedyncze klatki (próbkowane z częstotliwością 1 kl./s):
      • Jeśli parametr media_resolution ma wartość „low”, klatki są tokenizowane z częstotliwością 66 tokenów na klatkę.
      • W przeciwnym razie klatki są tokenizowane z częstotliwością 258 tokenów na klatkę.
    • Audio: 32 tokeny na sekundę.
    • Zawiera też metadane.
    • Łącznie: około 100 tokenów na sekundę filmu przy domyślnej (niskiej) rozdzielczości multimediów lub około 300 tokenów na sekundę filmu przy wysokiej rozdzielczości multimediów.
  • Obliczanie tokenów (tryb agenta): zużycie tokenów zależy od złożoności treści i strategii nawigacji modelu. Tokeny rozumowania nawigacyjnego generowane podczas eksploracji filmu są traktowane jako tokeny myślowe (total_thought_tokens), a klatki, dźwięk i transkrypcja wczytywane na żądanie są traktowane jako tokeny użycia narzędzia (total_tool_use_tokens). Przetwarzanie oparte na agentach zwykle zużywa do 88% mniej tokenów niż przetwarzanie statyczne w przypadku długich treści, ponieważ model wczytuje tylko transkrypcję lub klatki lub dźwięk, których potrzebuje do udzielenia odpowiedzi na prompt (patrz przewodnik po tokenach).
  • 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 do każdego obrazu wejściowego lub klatki filmu. Wyższe rozdzielczości zwiększają zdolność modelu do odczytywania drobnego tekstu lub rozpoznawania małych szczegółów, ale zwiększają zużycie tokenów i opóźnienia. Parametry media_resolution i processing są niezależne: możesz ustawić oba w tym samym wejściu wideo.

Więcej informacji o obliczaniu tokenów 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).
  • Miejsce docelowe promptu: jeśli łączysz tekst i jeden film, umieść prompt tekstowy po części wideo w tablicy input.
  • Przekroczenie czasu oczekiwania w przypadku długich żądań: w przypadku filmów, które wymagają dłuższego czasu przetwarzania lub złożonego, wieloetapowego rozumowania, używaj przesyłania strumieniowego (stream=True) lub wykonywania w tle (background=True). Synchroniczne żądania bez przesyłania strumieniowego, które w przypadku dużego zapotrzebowania powodują ponawianie prób po stronie backendu, mogą przekraczać okna ważności połączenia lub tokena uwierzytelniania, co może powodować nieoczekiwane błędy 401 Unauthorized lub przekroczenie czasu oczekiwania. Streaming utrzymuje aktywne połączenie i wyświetla pośrednie rozumowanie oraz postęp wywoływania narzędzi.

Co dalej?

  • Rozdzielczość multimediów: kontroluj rozdzielczość klatek wideo, aby zachować równowagę między jakością a wykorzystaniem tokenów.
  • Tokeny: dowiedz się, jak treści wideo są tokenizowane w trybach przetwarzania statycznego i przez agenta.
  • Instrukcje systemowe: instrukcje systemowe pozwalają sterować działaniem modelu na podstawie 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 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 weryfikatora są niezbędne, aby ograniczyć ryzyko szkód wynikających z takich danych wyjściowych.