הבנת סרטונים

במדריך Gemini Omni Flash יש מידע על יצירת סרטונים.

המודלים של Gemini יכולים לעבד סרטונים, וכך לאפשר למפתחים להשתמש בהם במגוון תרחישים מתקדמים שבעבר היו דורשים מודלים ספציפיים לתחום. חלק מיכולות הראייה של Gemini כוללות את היכולת: לתאר, לפלח ולחלץ מידע מסרטונים, לענות על שאלות לגבי קטע וידאו ולהתייחס לחותמות זמן ספציפיות בתוך סרטון.

אתם יכולים לתת ל-Gemini סרטונים כקלט בדרכים הבאות:

שיטת קלט גודל מקסימלי תרחיש שימוש מומלץ
File API ‫20GB (בתשלום) / 2GB (בחינם) קבצים גדולים (יותר מ-100MB), סרטונים ארוכים (יותר מ-10 דקות), קבצים לשימוש חוזר.
Cloud Storage Registration ‫2GB (לכל קובץ, ללא מגבלות אחסון) קבצים גדולים (יותר מ-100MB), סרטונים ארוכים (יותר מ-10 דקות), קבצים קבועים וקבצים לשימוש חוזר.
נתונים מוטבעים פחות מ-100MB קבצים קטנים (פחות מ-100MB), משך קצר (פחות מדקה), קלט חד-פעמי.
כתובות URL ב-YouTube לא רלוונטי סרטונים ציבוריים ב-YouTube.

הערה: מומלץ להשתמש ב-File API ברוב תרחישי השימוש, במיוחד בקבצים שגדולים מ-100MB או כשרוצים להשתמש שוב בקובץ בכמה בקשות.

מידע על שיטות אחרות להזנת קבצים, כמו שימוש בכתובות URL חיצוניות או בקבצים שמאוחסנים ב-Google Cloud, מופיע במדריך שיטות להזנת קבצים.

העלאת קובץ של סרטון

הקוד הבא מוריד סרטון לדוגמה, מעלה אותו באמצעות Files API, ממתין לעיבוד שלו ואז משתמש בהפניה לקובץ שהועלה כדי לסכם את הסרטון.

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

כדי לשפר את היעילות והביצועים של הטוקנים, כדאי להשתמש בעיבוד וידאו מבוסס-סוכן.

תמיד צריך להשתמש ב-Files API כשגודל הבקשה הכולל (כולל הקובץ, פרומפט טקסטואלי, הוראות המערכת וכו') גדול מ-20MB, משך נכס הווידאו ארוך או אם אתם מתכוונים להשתמש באותו סרטון בכמה הנחיות. ‫File API מקבל פורמטים של קובצי וידאו ישירות.

מידע נוסף על עבודה עם קובצי מדיה זמין במאמר Files API.

העברת נתוני וידאו בתוך השורה (inline)

במקום להעלות קובץ וידאו באמצעות File API, אפשר להעביר סרטונים קצרים יותר ישירות בבקשה. האפשרות הזו מתאימה לסרטונים קצרים שגודל הבקשה הכולל שלהם הוא פחות מ-20MB.

דוגמה להוספת נתוני וידאו בתוך השורה:

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

העברת כתובות URL ב-YouTube

אתם יכולים להעביר כתובות URL של YouTube ישירות ל-Gemini API כחלק מהבקשה, באופן הבא:

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

מגבלות:

  • בתוכנית החינמית, אי אפשר להעלות יותר מ-8 שעות של סרטוני YouTube ביום.
  • במינוי בתשלום, אין הגבלה לפי אורך הסרטון.
  • במודלים שקודמים ל-Gemini 2.5, אפשר להעלות רק סרטון אחד לכל בקשה. במודלים של Gemini 2.5 ואילך, אפשר להעלות עד 10 סרטונים בכל בקשה.
  • אפשר להעלות רק סרטונים שגלויים לכולם (לא סרטונים פרטיים או לא רשומים).

הבנת סרטונים על ידי סוכן

כברירת מחדל, קלט של וידאו מעובד באופן סטטי (חילוץ פריימים בקצב של פריים אחד לשנייה) בכל המודלים, כולל Gemini 4. המודלים Gemini 4 Argon,‏ 3.8 Flash,‏ 3.6 Flash ו-3.5 Flash Lite תומכים גם בהבנת סרטונים באמצעות סוכנים, מצב שצריך להפעיל באופן ידני שבו המודל בוחן באופן דינמי את ציר הזמן של הסרטון, בודק באופן סלקטיבי את התמלילים ומתאים באופן דינמי את קצב הפריימים והרזולוציה תוך כדי תנועה על סמך ההנחיה.

המצב תיאור דגמים נתמכים
סטטי (ברירת מחדל) הכלי מחלץ פריימים בקצב קבוע (1 FPS) ומציב אותם בהקשר במעבר יחיד. ברירת המחדל לכל המודלים של Gemini, כולל Gemini 4. כל המודלים של Gemini
Agentic המודל מנווט באופן דינמי בציר הזמן של הסרטון, וטוען רק את התוכן שהוא צריך על סמך ההנחיה. עד 88% יותר יעילות בשימוש בטוקנים ואיכות גבוהה יותר בכ-7% בתכנים ארוכים. ‫Gemini 4 Argon, ‏ ‎3.8 Flash, ‏ ‎3.6 Flash, ‏ ‎3.5 Flash Lite

בחירת מצב עיבוד

בוחרים את מצב העיבוד שמתאים לאורך הסרטון ולסוג השאילתה:

  • סטטי (ברירת מחדל): האפשרות הזו מתאימה לקליפים קצרים (עד 5 דקות), לסיכומים רחבים של סרטונים מלאים שבהם כל ההקלטה רלוונטית, לשאילתות שרגישות לזמן האחזור או לדיוק ברמת הפריים בכל הקליפ. בסרטונים קצרים או בהנחיות כלליות שדורשות בדיקה של רוב הסרטון, עיבוד סטטי חוסך את הטוקנים הנוספים של חשיבה (total_thought_tokens) ואת סבבי השליחה והקבלה של קריאות לפונקציות (total_tool_use_tokens) שנובעים מניווט בציר הזמן.
  • מבוסס-סוכן: הכי מתאים לסרטונים ארוכים (יותר מ-5-10 דקות), לאחזור של מחט בערימת שחת או לשאילתות שמטרגטות רגעים או נושאים ספציפיים. המודל בודק קודם את התמלילים וטוען רק קטעים חזותיים רלוונטיים לפי דרישה, וכך מפחית את השימוש בטוקנים של קלט וידאו בשיעור של עד 88% בלי למלא את חלון ההקשר.

הערה: בסרטונים ארוכים או בהנחיות מורכבות שבהן העיבוד של הסוכן נמשך יותר זמן, כדאי להשתמש בסטרימינג (stream=True) או בהרצה ברקע (background=True). כך החיבור נשאר פעיל, מוצגים שלבי ביניים של הסקת מסקנות ונמנעים מצבים של זמן קצוב לתפוגה של החיבור או האימות.

הגדרת מצב העיבוד

כדי להשתמש בהבנת סרטונים מבוססת-סוכן, מגדירים את "processing": "agentic" בחלק של הסרטון במערך input.

עיבוד סרטונים באמצעות סוכן AI יכול להימשך יותר זמן בסרטונים ארוכים, כי המודל מבצע כמה סבבי בדיקה כדי לנווט בציר הזמן. כדי למנוע אובדן של ההתקדמות אם החיבור לרשת מתנתק, בדוגמה הזו משתמשים ב-background=True כדי להריץ את המשימה באופן אסינכרוני בשרת. אפשר גם להריץ בקשות באופן סינכרוני בלי הרצת רקע, על ידי השמטת הפרמטר background, וזה מתאים במיוחד לסרטונים קצרים יותר.

במדריך בנושא הרצה ברקע מוסבר איך לבצע דגימה, לאחזר תוצאות ולנהל משימות ברקע.

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 with background execution
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?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

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 with background execution
let 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?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -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?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

הערה: כדי לוודא שהעיבוד באמצעות סוכן בוצע, בודקים את interaction.steps. הנוכחות של התגים processing_call ו-processing_result מציינת שהמודל ניווט בסרטון באופן דינמי.

שלבי התגובה

עיבוד אקטיבי מוסיף שני סוגים חדשים של שלבים למערך steps:

  • processing_call: המודל ביקש קטע וידאו או תמלול אודיו, שזוהו על ידי id.
  • ‫processing_result: התוצאה של הטעינה הזו, שמקושרת באמצעות call_id.

הן מופיעות לסירוגין עם שלבי thought (כשהסיכומים מופעלים) ולפני השלב הסופי של model_output. אפשר להשתמש בהן כדי להציג מעקב אחר ההתקדמות בממשק המשתמש, אבל הן לא דורשות תגובה.

בדוגמה הבאה מוצג המטען הייעודי (payload) של התגובה עם שלבי עיבוד משולבים:

{
  "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..."
        }
      ]
    }
  ]
}

שילוב של מצבי עיבוד שונים בסרטונים

הגדרת מצבי עיבוד שונים לכל סרטון באותה בקשה:

Python

import time
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")

# Use agentic processing with background execution
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."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

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" }
});

// Use agentic processing with background execution
let 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." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -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."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

שיחות וידאו עם זיכרון

ההקשר של הסרטון נשמר לאורך כל השיחה. כשמשתמשים בעיבוד מבוסס-סוכנים:

  • מצב עם שמירת מצב (באמצעות previous_interaction_id): השרת שומר את ההקשר של הסרטון. אין צורך בטיפול נוסף.
  • בלי שמירת מצב (באמצעות step_list): במצב בלי שמירת מצב, התגובה כוללת את השלבים processing_call ו-processing_result שמקודדים את ההקשר של הסרטון. כדי לשמור על ההקשר של הסרטון, צריך לכלול את כל השלבים מהתשובה ב-step_list של הבקשה הבאה. אם תשמיטו אותם, לא תקבלו שגיאת API, אבל ההקשר של הסרטון יאבד, ואיכות התשובות לשאלות ההמשך תרד באופן משמעותי. חשוב לזכור שהשלבים שמוחזרים ונשלחים בבקשות הבאות נכללים בספירת הטוקנים של הקלט.

התייחסות לחותמות זמן בתוכן

אתם יכולים לשאול שאלות על נקודות זמן ספציפיות בסרטון באמצעות חותמות זמן בפורמט 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?"

להפיק תובנות מפורטות מסרטון

מודלי Gemini מציעים יכולות מתקדמות להבנת קטע וידאו, על ידי עיבוד מידע גם מזרמי האודיו וגם מזרמי הווידאו. כך אפשר לחלץ מגוון רחב של פרטים, כולל יצירת תיאורים של מה שקורה בסרטון ומענה על שאלות לגבי התוכן שלו.

בתיאורים חזותיים, המודל דוגם את הסרטון בקצב של 1 פריימים לשנייה (FPS). תדירות הדגימה הזו כברירת מחדל מתאימה לרוב התכנים, אבל חשוב לדעת שהיא עלולה לפספס פרטים בסרטונים עם תנועה מהירה או שינויים מהירים בסצנות.

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

התאמה אישית של עיבוד הסרטונים

אתם יכולים להתאים אישית את עיבוד הסרטונים ב-Gemini API על ידי הגדרת מרווחי חיתוך או דגימה של קצב פריימים בהתאמה אישית. אפשרויות ההתאמה האישית האלה נתמכות רק כשמעבדים את הסרטון במצב "static".

הגדרת אינטרוולים של קטעי וידאו

אפשר לחתוך סרטון על ידי ציון start_offset ו-end_offset באובייקט ההגדרות האישיות של 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

הגדרת קצב פריימים מותאם אישית

כדי להגדיר דגימה של קצב פריימים בהתאמה אישית, מעבירים ארגומנט fps באובייקט ההגדרות האישיות 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

פורמטים נתמכים של סרטונים

‫Gemini תומך בסוגי ה-MIME הבאים של פורמטים של וידאו:

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

פרטים טכניים על סרטונים

  • מודלים נתמכים והקשר: כל מודלי Gemini יכולים לעבד נתוני וידאו.
    • מודלים עם חלון הקשר של מיליון טוקנים יכולים לעבד סרטונים באורך של עד 3 שעות כברירת מחדל (ברזולוציית מדיה נמוכה), או באורך של עד שעה ברזולוציית מדיה גבוהה.
  • מצבי עיבוד: המודלים Gemini 4 Argon,‏ 3.8 Flash,‏ 3.6 Flash,‏ 3.5 Flash Lite והמודלים הבאים תומכים בשני מצבי עיבוד וידאו:
    • סטטי: פריימים נשלפים בקצב של פריים אחד לשנייה ומוצבים בהקשר (ברירת המחדל לכל המודלים). האודיו מעובד בקצב של 1Kbps (ערוץ יחיד). חותמות הזמן מתווספות כל שנייה. האפשרות הזו הכי מתאימה לקליפים קצרים או כשכל פריים חשוב (למשל, בדיקה פריים אחרי פריים). שימו לב שרצפים מהירים של פעולות עלולים לאבד פרטים בגלל תדירות הדגימה של 1 FPS.
    • מבוסס-סוכן: המודל מנווט בסרטון באופן דינמי, וטוען תמליל, פריימים או אודיו לפי דרישה. השימוש בשיטה הזו מאפשר לצמצם את השימוש בטוקנים ב-88% כשמדובר בתוכן ארוך, אבל הניווט עשוי להגדיל את הזמן עד לטוקן הראשון (TTFT) ואת השימוש הכולל בטוקנים בקליפים קצרים (פחות מ-5 דקות) או בשאילתות רחבות, בגלל תהליכי חשיבה פנימיים ושימוש חוזר בכלים. הוא מתאים במיוחד לסרטונים ארוכים ולשאילתות ייעודיות, כדי לייעל את עלויות הטוקנים ואת איכות התשובות. התכונה נתמכת ב-Gemini 4 Argon,‏ 3.8 Flash,‏ 3.6 Flash ו-3.5 Flash Lite. פרטים נוספים זמינים במאמר הבנת סרטונים באמצעות סוכנים.
  • חישוב טוקנים (מצב סטטי): כל שנייה של סרטון מומרת לטוקנים באופן הבא:
    • פריימים בודדים (נדגמים בקצב של פריים אחד לשנייה):
      • אם media_resolution מוגדר כנמוך, הפריימים עוברים טוקניזציה בקצב של 66 טוקנים לכל פריים.
      • אחרת, הפריימים עוברים טוקניזציה לפי 258 טוקנים לכל פריים.
    • אודיו: 32 טוקנים לשנייה.
    • הוא כולל גם מטא-נתונים.
    • סה"כ: כ-100 טוקנים לשנייה של וידאו ברזולוציית מדיה (נמוכה) שמוגדרת כברירת מחדל, או כ-300 טוקנים לשנייה של וידאו ברזולוציית מדיה גבוהה.
  • חישוב טוקנים (מצב סוכן): השימוש בטוקנים משתנה בהתאם למורכבות התוכן ולאסטרטגיית הניווט של המודל. טוקנים של נימוקי ניווט שנוצרים במהלך חיפוש בסרטון נספרים כטוקנים של מחשבה (total_thought_tokens), ואילו פריימים, אודיו ותמליל שנטענים לפי דרישה נספרים כטוקנים של שימוש בכלי (total_tool_use_tokens). עיבוד באמצעות סוכן בדרך כלל צורך עד 88% פחות טוקנים כוללים מאשר עיבוד סטטי של תוכן ארוך, כי המודל טוען רק את התמליל או הפריימים או האודיו שהוא צריך כדי לענות על ההנחיה (ראו את המדריך לטוקנים).
  • רזולוציית מדיה: ב-Gemini 3 יש שליטה מדויקת בעיבוד של ראייה מולטימודלית באמצעות הפרמטר media_resolution. הפרמטר media_resolution קובע את המספר המקסימלי של טוקנים שהוקצו לכל תמונה או פריים של סרטון קלט. רזולוציות גבוהות יותר משפרות את היכולת של המודל לקרוא טקסט קטן או לזהות פרטים קטנים, אבל מגדילות את השימוש בטוקנים ואת זמן האחזור. הפרמטרים media_resolution ו-processing לא תלויים זה בזה: אפשר להגדיר את שניהם באותו קלט וידאו.

במדריך בנושא אסימונים מפורטים חישובים נוספים של אסימונים.

  • פורמט חותמת הזמן: כשמתייחסים לרגעים ספציפיים בסרטון בהנחיה, משתמשים בפורמט MM:SS (לדוגמה, 01:15 לדקה אחת ו-15 שניות).
  • מיקום ההנחיה: אם משלבים טקסט וסרטון אחד, צריך למקם את הנחיית הטקסט אחרי החלק של הסרטון במערך input.
  • פסק זמן לבקשות ארוכות: בסרטונים שנדרש להם זמן עיבוד ממושך או חשיבה רציונלית רב-שלבית מורכבת, כדאי להשתמש בסטרימינג (stream=True) או בהרצת תהליכים ברקע (background=True). בקשות סינכרוניות שאינן סטרימינג, שמתבצעים בהן ניסיונות חוזרים בעורף המערכת בביקוש גבוה, עלולות לחרוג מחלונות התוקף של החיבור או של אסימון האימות, ולגרום לשגיאות לא צפויות מסוג 401 Unauthorized או לשגיאות של פסק זמן. הסטרימינג שומר על החיבור פעיל ומציג את ההיגיון הביניים ואת התקדמות השימוש בכלים.

המאמרים הבאים

  • רזולוציית המדיה: שליטה ברזולוציה של פריימים של סרטונים כדי לאזן בין איכות לבין שימוש באסימונים.
  • טוקנים: הסבר על האופן שבו קטע וידאו עובר טוקניזציה במצבי עיבוד סטטיים וסוכניים.
  • הרצה ברקע: הרצה אסינכרונית של משימות ארוכות של ניתוח סרטונים כדי למנוע פסק זמן בחיבור.
  • ‫System instructions: הוראות מערכת מאפשרות לכוון את התנהגות המודל בהתאם לצרכים הספציפיים ולתרחישי השימוש שלכם.
  • ‫Files API: מידע נוסף על העלאה וניהול של קבצים לשימוש עם Gemini.
  • אסטרטגיות לפרומפטים באמצעות קבצים: Gemini API תומך בפרומפטים באמצעות נתוני טקסט, תמונה, אודיו ווידאו, שנקראים גם פרומפטים מולטי-מודאליים.
  • הנחיות בטיחות: לפעמים מודלים של AI גנרטיבי מפיקים פלטים לא צפויים, כמו פלטים לא מדויקים, מוטים או פוגעניים. כדי להגביל את הסיכון לפגיעה מהפלט, חיוני לבצע עיבוד לאחר הפקת הפלט והערכה אנושית.