הבנת סרטונים

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

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

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

קלט וידאו

יש כמה דרכים להזין סרטונים ל-Gemini:

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

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

אפשר להשתמש ב-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

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

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

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

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

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

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

REST

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

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

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

הכללת כתובת URL ב-YouTube

ממשקי Gemini API ו-AI Studio תומכים בכתובות URL של YouTube כנתוני קובץ Part. אתם יכולים לכלול כתובת URL של סרטון ב-YouTube בהנחיה שמבקשת מהמודל לסכם את תוכן הסרטון, לתרגם אותו או לבצע פעולות אחרות שקשורות לתוכן הסרטון.

מגבלות:

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

בדוגמה הבאה רואים איך לכלול כתובת URL של YouTube בהנחיה:

Python

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

JavaScript

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

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

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

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

אפשר לשאול שאלות על נקודות זמן ספציפיות בסרטון באמצעות חותמות זמן בפורמט 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 = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

REST

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

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

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

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

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

Python

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

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

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

Python

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

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

כברירת מחדל, המערכת דוגמת פריימים מהסרטון בקצב של פרים אחד לשנייה (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 טוקנים לשנייה של סרטון ברזולוציית מדיה נמוכה.
  • פורמט חותמת הזמן: כשמתייחסים לרגעים ספציפיים בסרטון בהנחיה, צריך להשתמש בפורמט MM:SS (לדוגמה, ‫01:15 למשך דקה ו-15 שניות).
  • שיטות מומלצות:
    • לקבלת תוצאות אופטימליות, מומלץ להשתמש רק בסרטון אחד לכל בקשת הנחיה.
    • אם משלבים טקסט וסרטון אחד, צריך למקם את הנחיית הטקסט אחרי החלק של הסרטון במערך contents.
    • חשוב לדעת שרצפי פעולות מהירים עלולים לאבד פרטים בגלל קצב הדגימה של 1 FPS. במקרה הצורך, אפשר להאט את הקליפים האלה.

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

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

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