درک ویدیویی

برای کسب اطلاعات در مورد تولید ویدیو، به راهنمای Gemini Omni Flash مراجعه کنید.

مدل‌های Gemini می‌توانند ویدیوها را پردازش کنند و بسیاری از موارد استفاده توسعه‌دهندگان پیشرو را که از نظر تاریخی به مدل‌های خاص دامنه نیاز داشتند، ممکن سازند. برخی از قابلیت‌های بینایی Gemini شامل توانایی توصیف، بخش‌بندی و استخراج اطلاعات از ویدیوها، پاسخ به سؤالات مربوط به محتوای ویدیو و ارجاع به مهرهای زمانی خاص در یک ویدیو است.

شما می‌توانید ویدیوها را به روش‌های زیر به عنوان ورودی به Gemini ارائه دهید:

روش ورودی حداکثر اندازه مورد استفاده توصیه شده
API فایل ۲۰ گیگابایت (پولی) / ۲ گیگابایت (رایگان) فایل‌های بزرگ (۱۰۰ مگابایت به بالا)، ویدیوهای طولانی (۱۰ دقیقه به بالا)، فایل‌های قابل استفاده مجدد.
ثبت نام فضای ابری ۲ گیگابایت (به ازای هر فایل، بدون محدودیت ذخیره‌سازی) فایل‌های بزرگ (۱۰۰ مگابایت به بالا)، ویدیوهای طولانی (۱۰ دقیقه به بالا)، فایل‌های ماندگار و قابل استفاده مجدد.
داده‌های درون‌خطی کمتر از ۱۰۰ مگابایت فایل‌های کوچک (کمتر از ۱۰۰ مگابایت)، مدت زمان کوتاه (کمتر از ۱ دقیقه)، ورودی‌های یکباره.
آدرس‌های اینترنتی یوتیوب ناموجود ویدیوهای عمومی یوتیوب.

نکته: API فایل برای اکثر موارد استفاده توصیه می‌شود، به خصوص برای فایل‌های بزرگتر از ۱۰۰ مگابایت یا زمانی که می‌خواهید از فایل در چندین درخواست دوباره استفاده کنید.

برای آشنایی با سایر روش‌های ورودی فایل، مانند استفاده از URLهای خارجی یا فایل‌های ذخیره شده در Google Cloud، به راهنمای روش‌های ورودی فایل مراجعه کنید.

آپلود فایل ویدیویی

کد زیر یک ویدیوی نمونه را دانلود می‌کند، آن را با استفاده از API فایل‌ها آپلود می‌کند، منتظر پردازش آن می‌ماند و سپس از مرجع فایل آپلود شده برای خلاصه کردن ویدیو استفاده می‌کند.

پایتون

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)

جاوا اسکریپت

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

برو

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())

استراحت

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

همیشه وقتی حجم کل درخواست (شامل فایل، متن درخواست، دستورالعمل‌های سیستم و غیره) بیشتر از 20 مگابایت است، مدت زمان ویدیو قابل توجه است، یا اگر قصد دارید از یک ویدیو در چندین درخواست استفاده کنید، از API فایل‌ها استفاده کنید. API فایل مستقیماً فرمت‌های فایل ویدیویی را می‌پذیرد.

برای کسب اطلاعات بیشتر در مورد کار با فایل‌های رسانه‌ای، به Files API مراجعه کنید.

انتقال داده‌های ویدیویی به صورت درون خطی

به جای آپلود فایل ویدیویی با استفاده از API فایل، می‌توانید ویدیوهای کوچک‌تر را مستقیماً در درخواست generateContent ارسال کنید. این روش برای ویدیوهای کوتاه‌تر با حجم کل درخواست کمتر از 20 مگابایت مناسب است.

در اینجا مثالی از ارائه داده‌های ویدیویی درون‌خطی آورده شده است:

پایتون

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)

جاوا اسکریپت

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

استراحت

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 را منتقل کنید

شما می‌توانید آدرس‌های اینترنتی یوتیوب را مستقیماً به عنوان بخشی از درخواست خود به API Gemini ارسال کنید، مانند زیر:

پایتون

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)

جاوا اسکریپت

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

برو

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

استراحت

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

محدودیت‌ها:

  • برای نسخه رایگان، نمی‌توانید بیش از ۸ ساعت ویدیوی یوتیوب در روز آپلود کنید.
  • برای نسخه پولی، هیچ محدودیتی بر اساس طول ویدیو وجود ندارد.
  • برای مدل‌های قبل از Gemini 2.5، می‌توانید فقط ۱ ویدیو در هر درخواست آپلود کنید. برای مدل‌های Gemini 2.5 و بالاتر، می‌توانید حداکثر ۱۰ ویدیو در هر درخواست آپلود کنید.
  • شما فقط می‌توانید ویدیوهای عمومی (ویدیوهای خصوصی یا ویدیوهای ثبت نشده) را آپلود کنید.

درک عامل‌مند ویدیو

به طور پیش‌فرض، ورودی‌های ویدیویی از پردازش استاتیک (استخراج فریم‌ها با سرعت ۱ فریم در ثانیه) استفاده می‌کنند. مدل‌های Gemini 3.8 Flash، 3.7 Flash، 3.6 Flash و 3.5 Flash Lite همچنین از درک عامل‌مند ویدیو پشتیبانی می‌کنند، که در آن مدل به صورت پویا جدول زمانی ویدیو را بررسی می‌کند، رونوشت‌ها را به صورت انتخابی بررسی می‌کند و نرخ فریم و وضوح را به صورت تطبیقی ​​​​در لحظه بر اساس درخواست تنظیم می‌کند.

حالت توضیحات مدل‌های پشتیبانی‌شده
استاتیک (پیش‌فرض) فریم‌ها را با نرخ ثابت (۱ فریم در ثانیه) استخراج می‌کند و آنها را در یک مرحله در متن قرار می‌دهد. برای کلیپ‌های کوتاه خوب کار می‌کند. همه مدل‌های جمینی
عامل این مدل به صورت پویا در جدول زمانی ویدیو پیمایش می‌کند و فقط محتوای مورد نیاز خود را بر اساس درخواست بارگذاری می‌کند. در محتوای طولانی، تا ۸۸٪ از نظر توکن کارآمدتر و حدود ۷٪ کیفیت بالاتری دارد. جمینی ۳.۸ فلش، ۳.۷ فلش، ۳.۶ فلش، ۳.۵ فلش لایت

انتخاب حالت پردازش

به عنوان یک راهنمای کلی، با حالت عامل شروع کنید، به خصوص هنگام بهینه‌سازی برای کیفیت پاسخ یا کارایی توکن.

  • عامل‌محور: ویدیوها یا کوئری‌های طولانی که لحظات خاص را هدف قرار می‌دهند. این مدل به صورت پویا در جدول زمانی پیمایش می‌کند تا اطلاعات مرتبط با متن را بدون پر کردن پنجره متن هدف قرار دهد.
  • ایستا: پرس‌وجوهای حساس به تأخیر در کلیپ‌های کوتاه (زیر ۵ دقیقه) یا مواردی که دقت در سطح فریم در کل کلیپ مورد نیاز است.

توجه: برای ویدیوهای طولانی یا درخواست‌های پیچیده که پردازش عامل‌محور زمان بیشتری می‌برد، از streaming ( client.models.generate_content_stream ) استفاده کنید. این کار اتصال را فعال نگه می‌دارد، مراحل استدلال میانی را پوشش می‌دهد و از وقفه‌های اتصال یا احراز هویت جلوگیری می‌کند.

تنظیم حالت پردازش

پایتون

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)

جاوا اسکریپت

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

برو

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())

استراحت

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 نشان می‌دهد که مدل به صورت پویا ویدیو را پیمایش کرده است.

نکته: برخلاف سایر ابزارهای سمت سرور (مانند جستجوی گوگل یا زمینه URL)، agentic video برای فراخوانی‌های ابزار و نتایجی که باید برگردانده یا پخش شوند، نیازی به تنظیم include_server_side_tool_invocations=True در ToolConfig ندارد. بخش‌های tool_call و tool_response برای پیمایش ویدیو، زمانی که media_processing="AGENTIC" روی هر بخش ورودی تنظیم شده باشد، به طور خودکار برگردانده می‌شوند.

ساختار پاسخ

وقتی پردازش عاملی فعال باشد، پاسخ شامل بخش‌های اضافی است که رد پیمایش داخلی را نشان می‌دهد:

  • tool_call parts ( tool_type: "MEDIA_PROCESSING" ) : هر بار که مدل یک بخش ویدیویی یا متن صوتی را درخواست می‌کند، منتشر می‌شود.
  • قطعات tool_response ( tool_type: "MEDIA_PROCESSING" ) : نتیجه هر عملیات بارگذاری.

لازم نیست این بخش‌ها را به صورت دستی مدیریت یا پاسخ دهید: پاسخ کامل را به عنوان تاریخچه مکالمه ارسال کنید و آنها به صورت خودکار مدیریت می‌شوند.

اگر include_thoughts=True در ThinkingConfig تنظیم شده باشد، مراحل استدلال به صورت بخش‌های thought: true که با جفت‌های فراخوانی/پاسخ ابزار در هم آمیخته شده‌اند، ظاهر می‌شوند. با غیرفعال بودن thoughts، متن thought حذف می‌شود اما بخش‌های ابزار هنوز وجود دارند.

مثال زیر، بار مفید پاسخ را با بخش‌های فراخوانی ابزار و پاسخ که به صورت درهم‌تنیده قرار گرفته‌اند، نشان می‌دهد:

{
  "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"
          }
        ]
      }
    }
  ]
}

حالت‌های پردازش را در ویدیوها با هم ترکیب کنید

شما می‌توانید حالت‌های پردازش مختلفی را برای هر بخش ویدیو در یک درخواست واحد تنظیم کنید:

پایتون

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)

جاوا اسکریپت

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

برو

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())

استراحت

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."}
      ]
    }]
  }'

برای ویدیوهای طولانی از ذخیره‌سازی زمینه‌ای استفاده کنید

برای ویدیوهایی که بیش از ۱۰ دقیقه طول می‌کشند، یا وقتی قصد دارید چندین درخواست برای یک فایل ویدیویی ارسال کنید، از ذخیره‌سازی زمینه‌ای (context caching) برای کاهش هزینه‌ها و بهبود تأخیر استفاده کنید. ذخیره‌سازی زمینه‌ای به شما امکان می‌دهد ویدیو را یک بار پردازش کنید و از توکن‌ها برای درخواست‌های بعدی دوباره استفاده کنید، که آن را برای جلسات چت یا تجزیه و تحلیل مکرر محتوای طولانی ایده‌آل می‌کند.

به مهرهای زمانی در محتوا اشاره کنید

شما می‌توانید با استفاده از مهرهای زمانی به شکل MM:SS ، در مورد نقاط زمانی خاص در ویدیو سؤال بپرسید.

پایتون

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

جاوا اسکریپت

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

برو

    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?"),
    }

استراحت

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

استخراج بینش‌های دقیق از ویدیو

مدل‌های Gemini با پردازش اطلاعات از جریان‌های صوتی و تصویری ، قابلیت‌های قدرتمندی برای درک محتوای ویدیو ارائه می‌دهند. این به شما امکان می‌دهد مجموعه‌ای غنی از جزئیات، از جمله تولید توضیحاتی در مورد آنچه در یک ویدیو اتفاق می‌افتد و پاسخ به سؤالات مربوط به محتوای آن را استخراج کنید.

برای توصیفات بصری، مدل از ویدیو با نرخ ۱ فریم در ثانیه (FPS) نمونه‌برداری می‌کند. این نرخ نمونه‌برداری پیش‌فرض برای اکثر محتواها به خوبی کار می‌کند، اما توجه داشته باشید که ممکن است در ویدیوهایی با حرکت سریع یا تغییرات سریع صحنه، جزئیات را از دست بدهد. برای چنین محتوای پرحرکتی، تنظیم نرخ فریم سفارشی را در نظر بگیرید.

پایتون

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

جاوا اسکریپت

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

برو

    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."),
    }

استراحت

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

سفارشی‌سازی پردازش ویدیو

شما می‌توانید پردازش ویدیو را در رابط برنامه‌نویسی نرم‌افزار Gemini با تنظیم فواصل برش یا ارائه نمونه‌برداری نرخ فریم سفارشی، سفارشی کنید. این گزینه‌های سفارشی‌سازی فقط هنگام پردازش ویدیو در حالت "static" پشتیبانی می‌شوند.

فواصل برش را تنظیم کنید

شما می‌توانید با مشخص کردن videoMetadata به همراه offsetهای شروع و پایان، ویدیو را برش دهید.

پایتون

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.')
        ]
    )
)

جاوا اسکریپت

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 نمونه‌برداری نرخ فریم سفارشی را تنظیم کنید.

پایتون

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.')
        ]
    )
)

به طور پیش‌فرض ۱ فریم در ثانیه (FPS) از ویدیو نمونه‌برداری می‌شود. ممکن است بخواهید FPS پایین (<1) را برای ویدیوهای طولانی تنظیم کنید. این امر به ویژه برای ویدیوهای عمدتاً ایستا (مثلاً سخنرانی‌ها) مفید است. برای ویدیوهایی که نیاز به تجزیه و تحلیل زمانی جزئی دارند، مانند درک سریع حرکت یا ردیابی حرکت با سرعت بالا، از FPS بالاتر استفاده کنید.

فرمت‌های ویدیویی پشتیبانی‌شده

Gemini از انواع MIME با فرمت‌های ویدیویی زیر پشتیبانی می‌کند:

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

جزئیات فنی در مورد ویدیوها

  • مدل‌ها و زمینه‌های پشتیبانی‌شده : همه مدل‌های Gemini می‌توانند داده‌های ویدیویی را پردازش کنند.
    • مدل‌هایی با پنجره زمینه ۱ مگابایتی می‌توانند به طور پیش‌فرض ویدیوهایی تا ۳ ساعت (با وضوح رسانه‌ای پایین) یا تا ۱ ساعت با وضوح رسانه‌ای بالا را پردازش کنند.
  • حالت‌های پردازش : Gemini 3.8 Flash، 3.7 Flash، 3.6 Flash، 3.5 Flash Lite و مدل‌های بعدی از دو حالت پردازش تصویر پشتیبانی می‌کنند:
    • استاتیک : فریم‌ها با سرعت ۱ فریم در ثانیه استخراج شده و در متن قرار می‌گیرند (پیش‌فرض برای همه مدل‌ها). صدا با سرعت ۱ کیلوبیت بر ثانیه (تک کانال) پردازش می‌شود. مهرهای زمانی هر ثانیه اضافه می‌شوند. بهترین حالت برای کلیپ‌های کوتاه یا زمانی است که هر فریم اهمیت دارد (مانند بررسی فریم به فریم). توجه داشته باشید که سکانس‌های اکشن سریع ممکن است به دلیل نرخ نمونه‌برداری ۱ فریم در ثانیه جزئیات را از دست بدهند.
    • Agentic : این مدل به صورت پویا در ویدیو پیمایش می‌کند و متن و/یا فریم‌ها و/یا صدا را بر اساس تقاضا بارگذاری می‌کند. این روش برای محتوای طولانی تا ۸۸٪ توکن کمتری استفاده می‌کند، اگرچه پیمایش ممکن است به دلیل استدلال داخلی و رفت و برگشت ابزار قبل از شروع تولید، زمان رسیدن به اولین توکن (TTFT) را در کلیپ‌های کوتاه (کمتر از ۵ دقیقه) کمی افزایش دهد. پاسخ‌ها شامل فراخوانی ابزار MEDIA_PROCESSING و بخش‌های پاسخ برای حفظ زمینه استدلال در طول نوبت‌ها هستند. بهترین گزینه برای ویدیوهای طولانی برای بهینه‌سازی هزینه‌های توکن و کیفیت پاسخ. پشتیبانی شده در Gemini 3.8 Flash، 3.7 Flash، 3.6 Flash و 3.5 Flash Lite. برای جزئیات بیشتر به بخش درک ویدیوی Agentic مراجعه کنید.
  • محاسبه توکن (حالت استاتیک) : هر ثانیه از ویدیو به صورت زیر توکن‌سازی می‌شود:
    • فریم‌های تکی (نمونه‌برداری شده با سرعت ۱ فریم در ثانیه):
      • اگر media_resolution روی مقدار پایین تنظیم شود، فریم‌ها با ۶۶ توکن در هر فریم توکن‌سازی می‌شوند.
      • در غیر این صورت، فریم‌ها با ۲۵۸ توکن در هر فریم توکن‌سازی می‌شوند.
    • صدا: ۳۲ توکن در ثانیه.
    • متادیتا نیز گنجانده شده است.
    • مجموع: تقریباً ۱۰۰ توکن در ثانیه از ویدیو با وضوح رسانه‌ای پیش‌فرض (پایین)، یا تقریباً ۳۰۰ توکن در ثانیه از ویدیو با وضوح رسانه‌ای بالا.
  • محاسبه توکن (حالت عامل) : استفاده از توکن بر اساس پیچیدگی محتوا و استراتژی ناوبری مدل متفاوت است. توکن‌های استدلال ناوبری که در طول کاوش ویدیو تولید می‌شوند، به عنوان توکن‌های تفکر ( thoughts_token_count ) در نظر گرفته می‌شوند، در حالی که فریم‌ها، صدا و متن بارگذاری شده بر اساس تقاضا، به عنوان توکن‌های ابزار اعلان ( tool_use_prompt_token_count ) در نظر گرفته می‌شوند. پردازش عامل معمولاً تا ۸۸٪ توکن‌های کمتری نسبت به پردازش استاتیک برای محتوای طولانی استفاده می‌کند، زیرا مدل فقط رونوشت و/یا فریم‌ها و/یا صوتی را که برای پاسخ به سوال نیاز دارد، بارگذاری می‌کند (به راهنمای توکن‌ها مراجعه کنید).
  • وضوح رسانه : Gemini 3 با پارامتر media_resolution کنترل دقیقی بر پردازش بینایی چندوجهی ارائه می‌دهد. پارامتر media_resolution حداکثر تعداد توکن‌های اختصاص داده شده به ازای هر تصویر ورودی یا فریم ویدیو را تعیین می‌کند. وضوح بالاتر، توانایی مدل را در خواندن متن ریز یا شناسایی جزئیات کوچک بهبود می‌بخشد، اما استفاده از توکن و تأخیر را افزایش می‌دهد. پارامترهای media_resolution و media_processing مستقل هستند: می‌توانید هر دو را روی یک قسمت ویدیو تنظیم کنید.

برای جزئیات بیشتر در مورد محاسبات توکن، به راهنمای توکن‌ها مراجعه کنید.

  • قالب مهر زمانی : هنگام اشاره به لحظات خاص در یک ویدیو در اعلان خود، از قالب MM:SS استفاده کنید (مثلاً 01:15 برای ۱ دقیقه و ۱۵ ثانیه).
  • قرار دادن اعلان : اگر متن و یک ویدیو را با هم ترکیب می‌کنید، اعلان متنی را بعد از بخش ویدیو در آرایه contents قرار دهید.
  • وقفه‌های زمانی برای درخواست‌های طولانی : برای ویدیوهایی که به زمان پردازش طولانی یا استدلال چند مرحله‌ای پیچیده نیاز دارند، از استریمینگ ( client.models.generate_content_stream ) استفاده کنید. درخواست‌های همزمان و غیر استریمینگ که با تقاضای بالا، تلاش‌های مجدد در backend را تجربه می‌کنند، می‌توانند از پنجره‌های اعتبارسنجی توکن اتصال یا احراز هویت تجاوز کنند، که ممکن است به صورت خطاهای غیرمنتظره 401 Unauthorized یا تایم اوت ظاهر شوند. استریمینگ اتصال را فعال نگه می‌دارد و استدلال میانی و پیشرفت فراخوانی ابزار را نمایش می‌دهد.

قدم بعدی چیست؟

  • وضوح رسانه : وضوح فریم‌های ویدیویی را کنترل کنید تا کیفیت و میزان استفاده از توکن را متعادل کنید.
  • توکن‌ها : نحوه توکنیزه کردن محتوای ویدیو در هر دو حالت پردازش ایستا و عامل‌محور را درک کنید.
  • دستورالعمل‌های سیستم : دستورالعمل‌های سیستم به شما امکان می‌دهند رفتار مدل را بر اساس نیازها و موارد استفاده خاص خود هدایت کنید.
  • API فایل‌ها : درباره آپلود و مدیریت فایل‌ها برای استفاده با Gemini بیشتر بدانید.
  • استراتژی‌های اعلان فایل : رابط برنامه‌نویسی نرم‌افزار Gemini از اعلان با داده‌های متنی، تصویری، صوتی و ویدیویی پشتیبانی می‌کند که به عنوان اعلان چندوجهی نیز شناخته می‌شود.
  • راهنمایی ایمنی : گاهی اوقات مدل‌های هوش مصنوعی مولد، خروجی‌های غیرمنتظره‌ای مانند خروجی‌های نادرست، جانبدارانه یا توهین‌آمیز تولید می‌کنند. پردازش پس از پردازش و ارزیابی انسانی برای محدود کردن خطر آسیب ناشی از چنین خروجی‌هایی ضروری است.