הבנת סרטונים

למידע ולמידה על יצירת סרטונים, ראו את המדריך של 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

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-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-3.8-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();

Go

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-3.8-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-3.8-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

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

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

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

העברת נתוני סרטונים בתוך התג

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

דוגמה לאספקת נתוני וידאו מוטמעים:

Python

from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-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.')
        ]
    )
)
print(response.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 contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-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-3.8-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

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

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

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-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.')
        ]
    )
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

const contents = [
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

Go

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-3.8-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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

מגבלות:

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

הבנת סרטונים באמצעות סוכנים

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

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

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

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

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

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

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

Python

import time
from google import genai
from google.genai import types

client = genai.Client()

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)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_file.uri,
            mime_type=video_file.mime_type,
            media_processing="AGENTIC",
        ),
        "What are the three main arguments presented?",
    ],
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

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

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: videoFile.uri,
            mimeType: videoFile.mimeType,
          },
          mediaProcessing: "AGENTIC",
        },
        { text: "What are the three main arguments presented?" },
      ],
    },
  ],
});
console.log(response.text);

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/lecture.mp4", nil)
parts := []*genai.Part{
    {
        FileData: &genai.FileData{
            FileURI:  uploadedFile.URI,
            MIMEType: uploadedFile.MIMEType,
        },
        MediaProcessing: genai.MediaProcessingAgentic,
    },
    genai.NewPartFromText("What are the three main arguments presented?"),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${file_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {"text": "What are the three main arguments presented?"}
      ]
    }]
  }'

הערה: כדי לוודא שהעיבוד באמצעות סוכן בוצע, בודקים את response.candidates[0].content.parts. הנוכחות של חלקים tool_call ו-tool_response עם סוג הכלי MEDIA_PROCESSING מציינת שהמודל ניווט בסרטון באופן דינמי.

הערה: בניגוד לכלים אחרים בצד השרת (כמו חיפוש Google או URL context), סוכן הווידאו לא דורש להגדיר את include_server_side_tool_invocations=True ב-ToolConfig כדי להחזיר או להעביר בסטרימינג קריאות לפונקציות ותוצאות. החלקים tool_call ו-tool_response של הניווט בסרטון מוחזרים אוטומטית כשמגדירים את media_processing="AGENTIC" בכל חלק של הקלט.

מבנה התשובה

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

  • ‫tool_call parts (tool_type: "MEDIA_PROCESSING"): נמדד בכל פעם שהמודל מבקש קטע וידאו או תמליל אודיו.
  • ‫tool_response parts (tool_type: "MEDIA_PROCESSING"): התוצאה של כל פעולת טעינה.

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

אם ההגדרה include_thoughts=True מוגדרת ב-ThinkingConfig, שלבי הנימוק מופיעים כחלקים thought: true שמשולבים עם זוגות של קריאות לכלים ותגובות. אם משביתים את התכונה 'מחשבות', הטקסט של המחשבות לא מוצג, אבל עדיין אפשר לראות את חלקי הכלים.

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

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "thought": true,
            "text": "Inspecting transcript for key discussion topics..."
          },
          {
            "thought_signature": "sig_A",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_B",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Loading visual frames to verify slide content..."
          },
          {
            "thought_signature": "sig_C",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_D",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Synthesizing answer from gathered evidence..."
          },
          {
            "text": "The three main arguments presented in the lecture are...",
            "thought_signature": "sig_E"
          }
        ]
      }
    }
  ]
}

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

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

Python

from google import genai
from google.genai import types

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",  # Use agentic video understanding
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",  # Use static processing
        ),
        "Compare the lecture content with the experiment results.",
    ],
)
print(response.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 response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: lecture.uri,
            mimeType: lecture.mimeType,
          },
          mediaProcessing: "AGENTIC", // Use agentic video understanding
        },
        {
          fileData: {
            fileUri: experiment.uri,
            mimeType: experiment.mimeType,
          },
          mediaProcessing: "STATIC", // Use static processing
        },
        { text: "Compare the lecture content with the experiment results." },
      ],
    },
  ],
});
console.log(response.text);

Go

lecturePart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  lectureFile.URI,
        MIMEType: lectureFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingAgentic, // Use agentic
}
experimentPart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  experimentFile.URI,
        MIMEType: experimentFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingStatic, // Use static
}
parts := []*genai.Part{
    lecturePart,
    experimentPart,
    genai.NewPartFromText("Compare the lecture content with the experiment results."),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${lecture_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {
          "file_data": {
            "file_uri": "'${experiment_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "STATIC"
        },
        {"text": "Compare the lecture content with the experiment results."}
      ]
    }]
  }'

שימוש בשמירת הקשר במטמון בסרטונים ארוכים

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

הפניה לחותמות זמן בתוכן

אתם יכולים לשאול שאלות על נקודות זמן ספציפיות בסרטון באמצעות חותמות זמן בפורמט MM:SS.

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "What are the examples given at 00:05 and 00:10 supposed to show us?",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "What are the examples given at 00:05 and 00:10 supposed to show us?",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("What are the examples given at 00:05 and 00:10 supposed to show us?"),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "What are the examples given at 00:05 and 00:10 supposed to show us?"}
        ]
      }]
    }' 2> /dev/null

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

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

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

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("Describe the key events in this video, providing both audio and visual details. " +
        "Include timestamps for salient moments."),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."}
        ]
      }]
    }' 2> /dev/null

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

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

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

כדי לחתוך סרטון, אפשר לציין את videoMetadata עם היסטים של התחלה וסיום.

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-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.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.8-flash';

async function main() {
const contents = [
  {
    role: 'user',
    parts: [
      {
        fileData: {
          fileUri: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mimeType: 'video/*',
        },
        videoMetadata: {
          startOffset: '40s',
          endOffset: '80s',
        }
      },
      {
        text: 'Please summarize the video in 3 sentences.',
      },
    ],
  },
];

const response = await ai.models.generateContent({
  model,
  contents,
});

console.log(response.text)

}

await main();

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

כדי להגדיר דגימה של קצב פריימים בהתאמה אישית, אפשר להעביר ארגומנט fps אל videoMetadata.

Python

from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-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.')
        ]
    )
)

JavaScript

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

const ai = new GoogleGenAI({});

const myfile = await ai.files.upload({
  file: "path/to/sample.mp4",
  mimeType: "video/mp4",
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      fileData: {
        fileUri: myfile.uri,
        mimeType: myfile.mimeType,
      },
      videoMetadata: {
        fps: 5,
      },
    },
    "Please summarize the video in 3 sentences.",
  ],
});

console.log(response.text);

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

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

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

  • video/mp4
  • video/mpeg
  • video/quicktime
  • 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 ומודלים מתקדמים יותר תומכים בשני מצבי עיבוד של סרטונים:
    • סטטי: הפריימים מחולצים בקצב של 1 FPS ומוצבים בהקשר (ברירת המחדל לכל המודלים). האודיו מעובד בקצב של 1Kbps (ערוץ יחיד). חותמות הזמן מתווספות כל שנייה. הכי מתאים לקליפים קצרים או כשכל פריים חשוב (למשל, כשבודקים פריים אחרי פריים). חשוב לזכור שרצפי פעולות מהירים עלולים לאבד פרטים בגלל קצב הדגימה של פריים אחד לשנייה.
    • מבוסס-סוכן: המודל מנווט באופן דינמי בסרטון, וטוען תמליל, פריימים או אודיו לפי דרישה. בשיטה הזו נעשה שימוש בעד 88% פחות אסימונים לתוכן ארוך, אבל הניווט עשוי להגדיל את הזמן עד לאסימון הראשון (TTFT) ואת השימוש הכולל באסימונים בקליפים קצרים (פחות מ-5 דקות) או בשאילתות רחבות, בגלל הסקת מסקנות פנימית וסבבי תקשורת של הכלים. התשובות כוללות חלקי MEDIA_PROCESSING קריאה לכלי ותשובה כדי לשמור על הקשר של הנימוקים בין התורות. המודל הכי מתאים לסרטונים ארוכים ולשאילתות ייעודיות, כדי לשפר את עלויות הטוקנים ואת איכות התשובות. התכונה נתמכת ב-Gemini 4 Argon,‏ 3.8 Flash,‏ 3.6 Flash ו-3.5 Flash Lite. פרטים נוספים זמינים במאמר בנושא הבנת סרטונים באמצעות סוכנים.
  • חישוב טוקנים (מצב סטטי): כל שנייה של סרטון מומרת לטוקנים באופן הבא:
    • פריימים בודדים (נדגמים בקצב של פריים אחד לשנייה):
      • אם media_resolution מוגדר כנמוך, הפריימים עוברים טוקניזציה בשיעור של 66 טוקנים לכל פריים.
      • אחרת, הפריימים עוברים טוקניזציה לפי 258 טוקנים לכל פריים.
    • אודיו: 32 טוקנים לשנייה.
    • המטא-נתונים כלולים גם הם.
    • סה"כ: כ-100 טוקנים לשנייה של וידאו ברזולוציית מדיה (נמוכה) שמוגדרת כברירת מחדל, או כ-300 טוקנים לשנייה של וידאו ברזולוציית מדיה גבוהה.
  • חישוב טוקנים (מצב סוכן): השימוש בטוקנים משתנה בהתאם למורכבות התוכן ולאסטרטגיית הניווט של המודל. טוקנים של חשיבה לניווט שנוצרים במהלך ניתוח הסרטון נחשבים כטוקנים של חשיבה (thoughts_token_count), ואילו פריימים, אודיו ותמלילים שנטענים על פי דרישה נחשבים כטוקנים של הנחיות לכלים (tool_use_prompt_token_count). עיבוד מבוסס-סוכנים בדרך כלל משתמש בעד 88% פחות טוקנים בסך הכול בהשוואה לעיבוד סטטי של תוכן ארוך, כי המודל טוען רק את התמליל ו/או הפריימים ו/או האודיו שנדרשים כדי לענות על ההנחיה (מידע נוסף זמין במדריך בנושא טוקנים).
  • רזולוציית מדיה: ב-Gemini 3 יש שליטה מפורטת על עיבוד הראייה המולטימודלי באמצעות הפרמטר media_resolution. הפרמטר media_resolution קובע את המספר המקסימלי של טוקנים שהוקצו לכל תמונה או פריים של סרטון קלט. רזולוציות גבוהות יותר משפרות את היכולת של המודל לקרוא טקסט קטן או לזהות פרטים קטנים, אבל מגדילות את השימוש בטוקנים ואת זמן האחזור. הפרמטרים media_resolution ו-media_processing לא תלויים זה בזה: אפשר להגדיר את שניהם באותו חלק של הסרטון.

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

  • פורמט חותמת הזמן: כשמפנים לרגעים ספציפיים בסרטון בהנחיה, צריך להשתמש בפורמט MM:SS (למשל, 01:15 ל-1 דקה ו-15 שניות).
  • מיקום ההנחיה: אם משלבים טקסט וסרטון אחד, צריך למקם את הנחיית הטקסט אחרי החלק של הסרטון במערך contents.
  • פסק זמן לבקשות ארוכות: בסרטונים שנדרש להם זמן עיבוד ממושך או חשיבה רציונלית רב-שלבית, מומלץ להשתמש בסטרימינג (client.models.generate_content_stream). בקשות סינכרוניות שלא מבוססות על סטרימינג, שמתבצעים בהן ניסיונות חוזרים בעורף המערכת בביקוש גבוה, עלולות לחרוג מחלונות התוקף של החיבור או של אסימון האימות, ולכן עלולות להופיע שגיאות 401 Unauthorized או שגיאות של פסק זמן. הסטרימינג שומר על החיבור פעיל ומציג את ההתקדמות של תהליך החשיבה ושל הקריאות לפונקציות.

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

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