הבנת סרטונים

אתם יכולים להוסיף סרטונים לבקשות מ-Gemini כדי לבצע משימות שכוללות הבנה של התוכן בסרטונים. בדף הזה נסביר איך להוסיף סרטונים לבקשות ל-Gemini ב-Gemini Enterprise Agent Platform באמצעות מסוף Google Cloud ו-Agent Platform API.

מודלים נתמכים

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

מודלים פרטים על המדיה סוגי MIME
  • אורך הסרטון המקסימלי (עם אודיו): 10 שניות
  • אורך הסרטון המקסימלי (ללא אודיו): 10 שניות
  • מספר הסרטונים המקסימלי לכל הנחיה: 3
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • אורך הסרטון המקסימלי (עם אודיו): 10 שניות
  • אורך הסרטון המקסימלי (ללא אודיו): 10 שניות
  • מספר הסרטונים המקסימלי לכל הנחיה: 3
  • יחסי גובה-רוחב נתמכים: ‫16:9, ‏ 9:16
  • רזולוציות נתמכות: 360p, ‏ 720p, ‏ 1080p, ‏ 4k
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • מספר מקסימלי של קובצי וידאו לקלט לכל פרומפט: 10
  • מספר כתובות ה-URL המקסימלי של סרטונים ב-YouTube שאפשר להוסיף להנחיה: 1
  • אורך הסרטון המקסימלי (ללא אודיו): בהתאם למה שנתמך בחלון ההקשר של 128k טוקנים (כ-25 דקות).
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • רזולוציית קלט רגילה: ‎768 x 768 (1 FPS)
  • רזולוציית הפלט המינימלית של האווטאר בזמן אמת: ‎704 x 1280 (לאורך) או ‎1280 x 704 (לרוחב) ב-24 FPS
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • אורך הסרטון המקסימלי (עם אודיו): כ-45 דקות
  • אורך סרטון מקסימלי (ללא אודיו): כשעה
  • מספר הסרטונים המקסימלי לכל הנחיה: ‫10
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • אורך הסרטון המקסימלי (עם אודיו): כ-45 דקות
  • אורך סרטון מקסימלי (ללא אודיו): כשעה
  • מספר הסרטונים המקסימלי לכל הנחיה: ‫10
  • ברירת המחדל של טוקנים לרזולוציה לכל פריים: ‫70
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • מספר מקסימלי של קובצי וידאו לקלט לכל פרומפט: 10
  • מספר כתובות ה-URL המקסימלי של סרטונים ב-YouTube שאפשר להוסיף להנחיה: 1
  • אורך הסרטון המקסימלי (ללא אודיו): בהתאם למה שנתמך בחלון הקשר של 65,536 טוקנים (כ-12 דקות).
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • רזולוציה רגילה: 768 x 768
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp

רשימת השפות שנתמכות במודלים של Gemini מופיעה במידע על המודלים מודלים של Google. מידע נוסף על עיצוב פרומפטים ל-multimodal אם אתם מחפשים דרך להשתמש ב-Gemini ישירות מהאפליקציות לנייד ומאפליקציות האינטרנט שלכם, כדאי לעיין בערכות ה-SDK של Firebase AI Logic ללקוחות עבור אפליקציות Swift,‏ Android,‏ Web,‏ Flutter ו-Unity.

הוספת סרטונים לבקשה

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

סרטון יחיד

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

המסוף

כדי לשלוח פרומפט מולטי-מודאלי באמצעות מסוף Google Cloud :

  1. בקטע Agent Platform במסוף Google Cloud , עוברים לדף Agent Studio.

    מעבר אל Agent Studio

  2. לוחצים על יצירת הנחיה.

  3. אופציונלי: מגדירים את המודל והפרמטרים:

    • מודל: בוחרים מודל.

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

    לוחצים כדי להרחיב את ההגדרות המתקדמות

    • Top-K: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך ל-Top-K.

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

      בכל שלב של בחירת אסימון, המערכת דוגמת את האסימונים המובילים מתוך K האסימונים עם ההסתברות הכי גבוהה. לאחר מכן, האסימונים מסוננים עוד יותר על סמך top-P, והאסימון הסופי נבחר באמצעות דגימת טמפרטורה.

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

    • Top-P: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך ל-Top-P. הטוקנים נבחרים מהסביר ביותר לסביר פחות עד שסכום ההסתברויות שלהם שווה לערך של top-P. כדי לקבל תוצאות עם הכי פחות שונות, מגדירים את top-P ל-0.
    • מספר מקסימלי של תשובות: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך למספר התשובות שרוצים ליצור.
    • הצגת התשובות כשהן מוכנות: אם מפעילים את ההגדרה הזו, התשובות יוצגו בזמן שהן נוצרות.
    • סף מסנן הבטיחות: בוחרים את הסף של הסבירות לקבלת תשובות שעלולות להיות מזיקות.
    • הפעלת Grounding: אין תמיכה ב-Grounding בהנחיות מולטימודאליות.
    • אזור: בוחרים את האזור שבו רוצים להשתמש.
    • טמפרטורה: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך לטמפרטורה.

          
The temperature is used for sampling during response generation, which occurs when topP
and topK are applied. Temperature controls the degree of randomness in token selection.
Lower temperatures are good for prompts that require a less open-ended or creative response, while
higher temperatures can lead to more diverse or creative results. A temperature of 0
means that the highest probability tokens are always selected. In this case, responses for a given
prompt are mostly deterministic, but a small amount of variation is still possible.


      If the model returns a response that's too generic, too short, or the model gives a fallback
response, try increasing the temperature. If the model enters infinite generation, increasing the
temperature to at least 0.1 may lead to improved results.
       1.0 is the
recommended starting value for temperature.
</li>
  <li>**Output token limit**: Use the slider or textbox to enter a value for
    the max output limit.

    
Maximum number of tokens that can be generated in the response. A token is
approximately four characters. 100 tokens correspond to roughly 60-80 words.


      Specify a lower value for shorter responses and a higher value for potentially longer
responses.
      
</li>
  <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a
    series of characters that includes spaces. If the model encounters a
    stop sequence, the response generation stops. The stop sequence isn't
    included in the response, and you can add up to five stop sequences.</li>
</ul>

  5. לוחצים על הוספת מדיה ובוחרים מקור לקובץ.

    העלאה

    בוחרים את הקובץ שרוצים להעלות ולוחצים על פתיחה.

    לפי כתובת URL

    מזינים את כתובת ה-URL של הקובץ שבו רוצים להשתמש ולוחצים על הוספה.

    YouTube

    מזינים את כתובת ה-URL של סרטון ב-YouTube שרוצים להשתמש בו ולוחצים על הוספה.

    אתם יכולים להשתמש בכל סרטון שגלוי לכולם או בסרטון שנמצא בבעלות החשבון שדרכו נכנסתם למסוף Google Cloud .

    Cloud Storage

    בוחרים את הדלי ואז את הקובץ מהדלי שרוצים לייבא ולוחצים על בחירה.

    Google Drive

    1. בפעם הראשונה שבוחרים באפשרות הזו, צריך לבחור חשבון ולתת ל-Agent Studio הסכמה לגשת לחשבון. אפשר להעלות כמה קבצים בגודל כולל של עד 10MB. הגודל המקסימלי של כל קובץ הוא 7MB.
    2. לוחצים על הקובץ שרוצים להוסיף.

    3. לוחצים על בחירה.

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

  6. כותבים את הפרומפט הטקסטואלי בחלונית פרומפט.

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

  8. לוחצים על שליחה.

  9. אופציונלי: כדי לשמור את ההנחיה בההנחיות שלי, לוחצים על שמירה.

  10. אופציונלי: כדי לקבל את קוד Python או פקודת curl להנחיה, לוחצים על יצירה עם קוד > קבלת קוד.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

Go

כאן מוסבר איך להתקין או לעדכן את Go.

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithMuteVideo shows how to generate text using a video with no sound as the input.
func generateWithMuteVideo(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What is in the video?"},
			{FileData: &genai.FileData{
				FileURI:  "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
				MIMEType: "video/mp4",
			}},
		},
			Role: genai.RoleUser},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The video shows several surfers riding waves in an ocean setting. The waves are ...

	return nil
}

Java

כאן מוסבר איך להתקין או לעדכן את Java.

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 


import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Part;

public class TextGenerationWithMuteVideo {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text with mute video input
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              Content.fromParts(
                  Part.fromUri(
                      "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
                      "video/mp4"),
                  Part.fromText("What is in this video?")),
              null);

      System.out.print(response.text());
      // Example response:
      // This video features **surfers in the ocean**.
      //
      // The main focus is on **one individual who catches and rides a wave**, executing various
      // turns and maneuvers as the wave breaks and dissipates into whitewater...
      return response.text();
    }
  }
}

Node.js

התקנה

npm install @google/genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateText(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
      {
        role: 'user',
        parts: [
          {
            fileData: {
              mimeType: 'video/mp4',
              fileUri:
                'gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4',
            },
          },
          {
            text: 'What is in the video?',
          },
        ],
      },
    ],
    config: {
      mediaResolution: 'MEDIA_RESOLUTION_LOW',
    },
  });

  console.log(response.text);

  // Example response:
  // The video shows several people surfing in an ocean with a coastline in the background. The camera ...

  return response.text;
}

REST

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

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט. .
  • ‫FILE_URI: ה-URI או כתובת ה-URL של הקובץ שרוצים לכלול בהנחיה. הערכים הקבילים כוללים את האפשרויות הבאות:
    • URI של קטגוריית Cloud Storage: האובייקט צריך להיות ניתן לקריאה באופן ציבורי או להיות באותו פרויקט Google Cloud ששולח את הבקשה.
    • כתובת URL מסוג HTTP: כתובת ה-URL של הקובץ צריכה להיות ניתנת לקריאה על ידי כולם. אפשר לציין קובץ וידאו אחד, קובץ אודיו אחד ועד 10 קבצים של תמונות בכל בקשה. הגודל המקסימלי של קובצי אודיו, קובצי וידאו ומסמכים הוא 15 MB.
    • כתובת ה-URL של סרטון ב-YouTube: הסרטון ב-YouTube צריך להיות בבעלות החשבון שבו השתמשתם כדי להיכנס למסוף Google Cloud או להיות גלוי לכולם. אפשר לציין רק כתובת URL אחת של סרטון ב-YouTube לכל בקשה.

    כשמציינים fileURI, צריך לציין גם את סוג המדיה (mimeType) של הקובץ. אם VPC Service Controls מופעל, אי אפשר לציין כתובת URL של קובץ מדיה עבור fileURI.

    אם אין לכם קובץ וידאו ב-Cloud Storage, אתם יכולים להשתמש בקובץ הבא שזמין לציבור: gs://cloud-samples-data/video/animals.mp4 עם סוג MIME של video/mp4. כדי לצפות בסרטון הזה, פותחים את קובץ ה-MP4 לדוגמה.

  • ‫MIME_TYPE: סוג המדיה של הקובץ שצוין בשדות data או fileUri. הערכים הקבילים כוללים את האפשרויות הבאות:

    לחיצה להרחבת סוגי MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • ‫TEXT: הוראות הטקסט שרוצים לכלול בהנחיה. לדוגמה: What is in the video?

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל: 

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל: 

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

שימו לב לפרטים הבאים בכתובת ה-URL של הדוגמה הזו:
  • משתמשים בשיטה generateContent כדי לבקש שהתשובה תוחזר אחרי שהיא נוצרת במלואה. כדי לצמצם את תפיסת זמן האחזור בקרב קהל אנושי, אפשר להזרים את התשובה בזמן שהיא נוצרת באמצעות השיטה streamGenerateContent.
  • מזהה המודל הרב-אופני מופיע בסוף כתובת ה-URL לפני השיטה (לדוגמה, gemini-3.5-flash). יכול להיות שהדוגמה הזו תתמוך גם במודלים אחרים.
  • כשמשתמשים בנקודת קצה אזורית של API (לדוגמה, us-central1), האזור מכתובת ה-URL של נקודת הקצה קובע איפה הבקשה תעובד. המערכת מתעלמת מכל מיקום שמתנגש בנתיב המשאב.

סרטון עם אודיו

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

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

REST

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

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫FILE_URI: ה-URI או כתובת ה-URL של הקובץ שרוצים לכלול בהנחיה. הערכים הקבילים כוללים את האפשרויות הבאות:
    • URI של קטגוריית Cloud Storage: האובייקט צריך להיות ניתן לקריאה באופן ציבורי או להיות באותו פרויקט Google Cloud ששולח את הבקשה.
    • כתובת URL מסוג HTTP: כתובת ה-URL של הקובץ צריכה להיות ניתנת לקריאה על ידי כולם. אפשר לציין קובץ וידאו אחד, קובץ אודיו אחד ועד 10 קבצים של תמונות בכל בקשה. הגודל המקסימלי של קובצי אודיו, קובצי וידאו ומסמכים הוא 15 MB.
    • כתובת ה-URL של סרטון ב-YouTube: הסרטון ב-YouTube צריך להיות בבעלות החשבון שבו השתמשתם כדי להיכנס למסוף Google Cloud או להיות גלוי לכולם. אפשר לציין רק כתובת URL אחת של סרטון ב-YouTube לכל בקשה.

    כשמציינים fileURI, צריך לציין גם את סוג המדיה (mimeType) של הקובץ. אם VPC Service Controls מופעל, אי אפשר לציין כתובת URL של קובץ מדיה עבור fileURI.

    אם אין לכם קובץ וידאו ב-Cloud Storage, אתם יכולים להשתמש בקובץ הבא שזמין לציבור: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 עם סוג MIME של video/mp4. כדי לצפות בסרטון הזה, פותחים את קובץ ה-MP4 לדוגמה.

  • ‫MIME_TYPE: סוג המדיה של הקובץ שצוין בשדות data או fileUri. הערכים הקבילים כוללים את האפשרויות הבאות:

    לחיצה להרחבת סוגי MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
     
  • TEXT
     הוראות הטקסט שייכללו בפרומפט. לדוגמה: Provide a description of the video. The description should also contain anything important which people say in the video.

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל: 

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל: 

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

שימו לב לפרטים הבאים בכתובת ה-URL של הדוגמה הזו:
  • משתמשים בשיטה generateContent כדי לבקש שהתשובה תוחזר אחרי שהיא נוצרת במלואה. כדי לצמצם את תפיסת זמן האחזור בקרב קהל אנושי, אפשר להזרים את התשובה בזמן שהיא נוצרת באמצעות השיטה streamGenerateContent.
  • מזהה המודל הרב-אופני מופיע בסוף כתובת ה-URL לפני השיטה (לדוגמה, gemini-3.5-flash). יכול להיות שהדוגמה הזו תתמוך גם במודלים אחרים.
  • כשמשתמשים בנקודת קצה אזורית של API (לדוגמה, us-central1), האזור מכתובת ה-URL של נקודת הקצה קובע איפה הבקשה תעובד. המערכת מתעלמת מכל מיקום שמתנגש בנתיב המשאב.

המסוף

כדי לשלוח פרומפט מולטי-מודאלי באמצעות מסוף Google Cloud :

  1. בקטע Agent Platform במסוף Google Cloud , עוברים לדף Agent Studio.

    מעבר אל Agent Studio

  2. לוחצים על יצירת הנחיה.

  3. אופציונלי: מגדירים את המודל והפרמטרים:

    • מודל: בוחרים מודל.

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

    לוחצים כדי להרחיב את ההגדרות המתקדמות

    • Top-K: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך ל-Top-K.

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

      בכל שלב של בחירת אסימון, המערכת דוגמת את האסימונים המובילים מתוך K האסימונים עם ההסתברות הכי גבוהה. לאחר מכן, האסימונים מסוננים עוד יותר על סמך top-P, והאסימון הסופי נבחר באמצעות דגימת טמפרטורה.

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

    • Top-P: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך ל-Top-P. הטוקנים נבחרים מהסביר ביותר לסביר פחות עד שסכום ההסתברויות שלהם שווה לערך של top-P. כדי לקבל תוצאות עם הכי פחות שונות, מגדירים את top-P ל-0.
    • מספר מקסימלי של תשובות: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך למספר התשובות שרוצים ליצור.
    • הצגת התשובות כשהן מוכנות: אם מפעילים את ההגדרה הזו, התשובות יוצגו בזמן שהן נוצרות.
    • סף מסנן הבטיחות: בוחרים את הסף של הסבירות לקבלת תשובות שעלולות להיות מזיקות.
    • הפעלת Grounding: אין תמיכה ב-Grounding בהנחיות מולטימודאליות.
    • אזור: בוחרים את האזור שבו רוצים להשתמש.
    • טמפרטורה: משתמשים בפס ההזזה או בתיבת הטקסט כדי להזין ערך לטמפרטורה.

          
The temperature is used for sampling during response generation, which occurs when topP
and topK are applied. Temperature controls the degree of randomness in token selection.
Lower temperatures are good for prompts that require a less open-ended or creative response, while
higher temperatures can lead to more diverse or creative results. A temperature of 0
means that the highest probability tokens are always selected. In this case, responses for a given
prompt are mostly deterministic, but a small amount of variation is still possible.


      If the model returns a response that's too generic, too short, or the model gives a fallback
response, try increasing the temperature. If the model enters infinite generation, increasing the
temperature to at least 0.1 may lead to improved results.
       1.0 is the
recommended starting value for temperature.
</li>
  <li>**Output token limit**: Use the slider or textbox to enter a value for
    the max output limit.

    
Maximum number of tokens that can be generated in the response. A token is
approximately four characters. 100 tokens correspond to roughly 60-80 words.


      Specify a lower value for shorter responses and a higher value for potentially longer
responses.
      
</li>
  <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a
    series of characters that includes spaces. If the model encounters a
    stop sequence, the response generation stops. The stop sequence isn't
    included in the response, and you can add up to five stop sequences.</li>
</ul>

  5. לוחצים על הוספת מדיה ובוחרים מקור לקובץ.

    העלאה

    בוחרים את הקובץ שרוצים להעלות ולוחצים על פתיחה.

    לפי כתובת URL

    מזינים את כתובת ה-URL של הקובץ שבו רוצים להשתמש ולוחצים על הוספה.

    YouTube

    מזינים את כתובת ה-URL של סרטון ב-YouTube שרוצים להשתמש בו ולוחצים על הוספה.

    אתם יכולים להשתמש בכל סרטון שגלוי לכולם או בסרטון שנמצא בבעלות החשבון שדרכו נכנסתם למסוף Google Cloud .

    Cloud Storage

    בוחרים את הדלי ואז את הקובץ מהדלי שרוצים לייבא ולוחצים על בחירה.

    Google Drive

    1. בפעם הראשונה שבוחרים באפשרות הזו, צריך לבחור חשבון ולתת ל-Agent Studio הסכמה לגשת לחשבון. אפשר להעלות כמה קבצים בגודל כולל של עד 10MB. הגודל המקסימלי של כל קובץ הוא 7MB.
    2. לוחצים על הקובץ שרוצים להוסיף.

    3. לוחצים על בחירה.

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

  6. כותבים את הפרומפט הטקסטואלי בחלונית פרומפט.

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

  8. לוחצים על שליחה.

  9. אופציונלי: כדי לשמור את ההנחיה בההנחיות שלי, לוחצים על שמירה.

  10. אופציונלי: כדי לקבל את קוד Python או פקודת curl להנחיה, לוחצים על יצירה עם קוד > קבלת קוד.

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

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

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

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

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

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

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

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

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

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

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

מודלים וסוגי קבצים נתמכים

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

כדי להרחיב את רשימת המודלים הנתמכים, לוחצים כאן

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

  • כתובות URL ב-YouTube
  • מזהי URI של Cloud Storage
  • קובצי וידאו מוטבעים בקידוד Base64

מתי כדאי להשתמש בהבנת וידאו מבוססת-סוכן

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

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

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

אפשר להשתמש ב-GenerateContent API כדי להבין סרטונים באמצעות סוכנים. משתמשים בmedia_processing = "AGENTIC" בבקשה:

Python 

from google import genai
from google.genai import types

client = genai.Client()

# Example: Controlling media_processing explicitly
video_part = types.Part(
  file_data=types.FileData(
      file_uri="gs://my-bucket-name/sports_clip.mp4",
      mime_type="video/mp4",
  ),
  media_processing="agentic" # Options: "agentic", "static"
)

response = client.models.generate_content(
  model="gemini-3.7-flash",
  contents=[
      video_part,
      "Analyze the player's footwork right before the shot."
  ]
)
print(response.text)

REST 

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1beta1/projects/YOUR_PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent \
-d '{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}'

ההגדרה של הבנת סרטונים באמצעות סוכנים מוגדרת כ-STATIC או מושבתת כברירת מחדל בכל הדגמים הנתמכים.

שינוי רזולוציית המדיה

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

הגדרת פרמטרים אופציונליים של המודל

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

טוקניזציה של סרטונים

ב-Gemini 3, טוקניזציה של סרטונים מתבצעת באמצעות אורך רצף משתנה, שמחליף את השיטה של Pan and Scan ששימשה במודלים קודמים, כדי לשפר את האיכות ואת זמן האחזור.

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

הרזולוציות הבאות זמינות במודלים של Gemini 3:

  • ‫MEDIA_RESOLUTION_HIGH: 280 טוקנים לכל פריים
  • ‫MEDIA_RESOLUTION_MEDIUM: 70 טוקנים לכל פריים
  • ‫MEDIA_RESOLUTION_LOW: 70 טוקנים לכל פריים
  • ‫MEDIA_RESOLUTION_UNSPECIFIED: 70 טוקנים לכל פריים (ברירת מחדל)

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

בדוגמת הקוד הזו אפשר לראות איך משנים את media_resolution:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.1-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH
          ),
      ),
      Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
              mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

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

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

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

בנוסף, לגבי מודלים של Gemini 3, חשוב לזכור את הנקודות הבאות:

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

מגבלות

מודלים מולטי-מודאליים של Gemini הם עוצמתיים במקרים רבים של שימוש מולטי-מודאלי, אבל חשוב להבין את המגבלות של המודלים:

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

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

  • עיבוד באמצעות File API: כשמשתמשים ב-File API, הסרטונים נדגמים ב-1 פריימים לשנייה (FPS) והשמע מעובד ב-1Kbps (ערוץ יחיד). חותמות הזמן מתווספות כל שנייה.

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

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

    • לשיעורי דגימה של FPS אחד או פחות: משתמשים בפורמט MM:SS, שבו שתי הספרות הראשונות מייצגות דקות ושתי הספרות האחרונות מייצגות שניות. אם יש לכם היסטים של יותר משעה, השתמשו בפורמט H:MM:SS.

    • לשיעורי דגימה מעל 1 FPS: משתמשים בפורמט MM:SS.sss, או, אם יש לכם היסטים של יותר משעה אחת, משתמשים בפורמט H:MM:SS.sss, שמתואר באופן הבא:

      • הספרה הראשונה מייצגת את השעה.
      • שתי הספרות הבאות מייצגות דקות.
      • שתי הספרות השלישיות מייצגות שניות.
      • שלוש הספרות האחרונות מייצגות חלקיקי שנייה.

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

    • כדי לקבל תוצאות אופטימליות, מומלץ להשתמש רק בסרטון אחד בכל בקשת פרומפט.

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

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

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