הבנת סרטונים

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

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

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

לפני שמתחילים

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

קלט וידאו

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

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

העלאת קובץ וידאו

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

‏File API מקבל פורמטים של קובצי וידאו ישירות. בדוגמה הזו נעשה שימוש בסרט הקצר של NASA‏ "Jupiter's Great Red Spot Shrinks and Grows". קרדיט: מרכז טיסות החלל גודארד (GSFC)/David Ladd (2018).

הסרטון 'הכתם האדום הגדול בכוכב יופיטר מתכווץ וגדל' הוא נחלת הכלל ואין בו אנשים שאפשר לזהות. (הנחיות לשימוש בתמונות ובמדיה של NASA)

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

Python

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

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

response = client.models.generate_content(
    model="gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });

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

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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.0-flash:generateContent?key=$GOOGLE_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 בכל יום.
  • אפשר להעלות רק סרטון אחד בכל בקשה.
  • אפשר להעלות רק סרטונים שגלויים לכולם (לא סרטונים פרטיים או לא רשומים).

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

Python

response = client.models.generate_content(
    model='models/gemini-2.0-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

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
  genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
  genai.Text("Please summarize the video in 3 sentences."))
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text.
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
         // Adjusted timestamps for the NASA video
        genai.Text("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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
        genai.Text("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 תומך בסוגי ה-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 מיליון טוקנים יכולים לעבד סרטונים באורך של עד שעתיים, ואילו מודלים עם חלון הֶקשר של מיליון טוקנים יכולים לעבד סרטונים באורך של עד שעה.
  • עיבוד באמצעות File API: כשמשתמשים ב-File API, הסרטונים נלקחים לדגימה בקצב של ‎1 frame לשנייה (FPS) והאודיו עובר עיבוד בקצב של ‎1Kbps (ערוץ יחיד). חותמות הזמן מתווספות בכל שנייה.
    • השיעורים האלה עשויים להשתנות בעתיד כדי לשפר את ההסקה.
  • חישוב האסימונים: כל שנייה בסרטון מומרת לאסימון באופן הבא:
    • פריימים בודדים (דגימה בקצב 1FPS): 258 אסימונים לכל פריים.
    • אודיו: 32 אסימונים לשנייה.
    • גם המטא-נתונים כלולים.
    • סה"כ: כ-300 אסימונים לשנייה של סרטון.
  • פורמט של חותמת זמן: כשאתם מתייחסים לרגעים ספציפיים בסרטון בהנחיה, השתמשו בפורמט MM:SS (למשל, 01:15 למשך דקה ו-15 שניות).
  • שיטות מומלצות:
    • כדי להשיג תוצאות מיטביות, מומלץ להשתמש רק בסרטון אחד לכל בקשה להנחיה.
    • אם משלבים טקסט וסרטון אחד, צריך למקם את הנחיית הטקסט אחרי חלק הסרטון במערך contents.
    • חשוב לדעת שסצנות פעולה מהירות עשויות לאבד פרטים בגלל קצב הדגימה של 1FPS. אם צריך, כדאי להאט את הקליפ.

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

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

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