הבנת סרטונים

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

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

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

קלט וידאו

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

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

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

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

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

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

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

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

fmt.Println(result.Text())

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
echo file_uri=$file_uri

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

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}]
        }]
      }' 2> /dev/null > response.json

jq -r ".candidates[].content.parts[].text" response.json

מידע נוסף על עבודה עם קובצי מדיה זמין במאמר בנושא 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='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

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

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"video/mp4",
                "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'"
              }
            },
            {"text": "Please summarize the video in 3 sentences."}
        ]
      }]
    }' 2> /dev/null

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

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

Python

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.response.text());

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

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {"text": "Please summarize the video in 3 sentences."},
            {
              "file_data": {
                "file_uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
              }
            }
        ]
      }]
    }' 2> /dev/null

מגבלות:

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

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

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

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?" # Adjusted timestamps for the NASA video

JavaScript

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

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

REST

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

חילוץ תובנות מפורטות מסרטון

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

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

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("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 על ידי הגדרת מרווחי חיתוך או על ידי מתן דגימה מותאמת אישית של קצב הפריימים.

הגדרת מרווחי חיתוך

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

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-2.5-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-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

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

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

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

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

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

  • מודלים נתמכים והקשר: כל המודלים של Gemini 2.0 ו-2.5 יכולים לעבד נתוני וידאו.
    • מודלים עם חלון הקשר של 2 מיליון טוקנים יכולים לעבד סרטונים באורך של עד שעתיים ברזולוציית מדיה שמוגדרת כברירת מחדל, או באורך של עד 6 שעות ברזולוציית מדיה נמוכה. מודלים עם חלון הקשר של מיליון טוקנים יכולים לעבד סרטונים באורך של עד שעה ברזולוציית מדיה שמוגדרת כברירת מחדל, או באורך של עד 3 שעות ברזולוציית מדיה נמוכה.
  • עיבוד באמצעות File API: כשמשתמשים ב-File API, סרטונים מאוחסנים ב-1 פריימים לשנייה (FPS) ואודיו מעובד ב-1Kbps (ערוץ יחיד). חותמות הזמן מתווספות כל שנייה.
  • חישוב הטוקנים: כל שנייה של סרטון מומרת לטוקן באופן הבא:
    • פריימים בודדים (נדגמים ב-1 FPS):
      • אם הערך של mediaResolution מוגדר כנמוך, הפריימים עוברים טוקניזציה בשיעור של 66 טוקנים לכל פרים.
      • אחרת, הפריימים עוברים טוקניזציה בקצב של 258 טוקנים לכל פריים.
    • אודיו: 32 טוקנים לשנייה.
    • המטא-נתונים כלולים גם הם.
    • סך הכול: כ-300 טוקנים לשנייה של וידאו ברזולוציית מדיה שמוגדרת כברירת מחדל, או 100 טוקנים לשנייה של וידאו ברזולוציית מדיה נמוכה.
  • רזולוציה בינונית: ב-Gemini 3 יש שליטה מדויקת בעיבוד של ראייה מולטימודאלית באמצעות הפרמטר media_resolution. הפרמטר media_resolution קובע את המספר המקסימלי של טוקנים שמוקצים לכל תמונה או פריים של סרטון קלט. רזולוציות גבוהות יותר משפרות את היכולת של המודל לקרוא טקסט קטן או לזהות פרטים קטנים, אבל מגדילות את השימוש באסימונים ואת זמן האחזור.

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

  • פורמט חותמת הזמן: כשמתייחסים לרגעים ספציפיים בסרטון בהנחיה, צריך להשתמש בפורמט MM:SS (לדוגמה, ‫01:15 למשך דקה ו-15 שניות).

  • שיטות מומלצות:

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

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

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

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