درک ویدیو

برای آشنایی با تولید ویدیو، راهنمای Gemini Omni Flash را ببینید.

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

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

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

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

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

بارگذاری فایل ویدیویی

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

Python

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)

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

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

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

همیشه وقتی اندازه کل درخواست (شامل فایل، پیام‌واره نوشتاری، دستورالعمل‌های سیستم، و غیره) بزرگ‌تر از ۲۰ مگابایت است، مدت ویدیو قابل‌توجه است، یا اگر قصد دارید از ویدیو یکسانی در پیام‌واره‌های متعددی استفاده کنید، از «میانای برنامه‌سازی کاربردی فایل‌ها» استفاده کنید. «میانای برنامه‌سازی کاربردی فایل» قالب‌های فایل ویدیویی را مستقیماً می‌پذیرد.

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

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

به‌جای بارگذاری فایل ویدیو بااستفاده از «میانای برنامه کاربردی فایل»، می‌توانید ویدیوهای کوچک‌تر را مستقیماً در درخواست به generateContent ارسال کنید. این برای ویدیوهای کوتاه‌تر با اندازه کل درخواست کمتر از ۲۰ مگابایت مناسب است.

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

Python

from google import genai
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='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)

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-3.8-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-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

نشانی‌های وب YouTube را ارسال کنید

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

Python

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)

JavaScript

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

REST

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

محدودیت‌ها:

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

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

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

حالت شرح مدل‌های پشتیبانی‌شده
ایستا (پیش‌فرض) قاب‌ها را با نرخ ثابت (۱ قاب در ثانیه) استخراج می‌کند و آن‌ها را در یک گذر در بافت قرار می‌دهد. برای کلیپ‌های کوتاه خوب کار می‌کند. همه مدل‌های Gemini
Agentic این مدل به‌صورت پویا در خط زمان ویدیو پیمایش می‌کند و فقط محتوایی را که براساس پیام‌واره نیاز دارد بار می‌کند. تا ۸۸٪ کارآمدتر ازنظر تعداد نشان و ~۷٪ کیفیت بالاتر در محتوای بلند. Gemini 3.8 Flash،‏ 3.6 Flash،‏ 3.5 Flash Lite

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

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

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

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

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

Python

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)

JavaScript

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

REST

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

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

ساختار پاسخ

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

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

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

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

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

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

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

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

Python

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)

JavaScript

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

REST

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

استفاده از حافظه نهان زمینه‌ای برای ویدیوهای طولانی

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

به مُهرهای زمان در محتوا مراجعه کنید

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

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "What are the examples given at 00:05 and 00:10 supposed to show us?",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "What are the examples given at 00:05 and 00:10 supposed to show us?",
  ],
});
console.log(response.text);

رفتن

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("What are the examples given at 00:05 and 00:10 supposed to show us?"),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

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": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "What are the examples given at 00:05 and 00:10 supposed to show us?"}
        ]
      }]
    }' 2> /dev/null

استخراج اطلاعات آماری دقیق از ویدیو

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

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

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
  ],
});
console.log(response.text);

رفتن

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("Describe the key events in this video, providing both audio and visual details. " +
        "Include timestamps for salient moments."),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

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": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."}
        ]
      }]
    }' 2> /dev/null

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

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

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

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

Python

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

JavaScript

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

Python

from google import genai
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-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.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

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

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      fileData: {
        fileUri: myfile.uri,
        mimeType: myfile.mimeType,
      },
      videoMetadata: {
        fps: 5,
      },
    },
    "Please summarize the video in 3 sentences.",
  ],
});

console.log(response.text);

به‌طور پیش‌فرض، ۱ فریم در ثانیه (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.6 Flash،‏ 3.5 Flash Lite، و مدل‌های جدیدتر از دو حالت پردازش ویدیو پشتیبانی می‌کنند:
    • ایستا: قاب‌ها با نرخ ۱ فریم در ثانیه استخراج می‌شوند و در بافت قرار می‌گیرند (پیش‌فرض برای همه مدل‌ها). صدا با سرعت ۱ کیلوبیت در ثانیه (تک‌کاناله) پردازش می‌شود. مُهرهای زمان هر ثانیه اضافه می‌شوند. بهترین برای کلیپ‌های کوتاه یا زمانی که هر قاب اهمیت دارد (مانند بازرسی قاب‌به‌قاب). توجه داشته باشید که توالی‌های کنش سریع ممکن است به‌دلیل نرخ نمونه‌برداری ۱ فریم در ثانیه جزئیات را ازدست بدهند.
    • عامل‌محور: مدل به‌صورت پویا در ویدیو پیمایش می‌کند و ترانویسی و/یا قاب‌ها و/یا صدا را به‌درخواست بار می‌کند. این مدل برای محتوای طولانی تا ۸۸٪ کمتر از نشان‌ها استفاده می‌کند، هرچند ممکن است به‌دلیل استدلال داخلی و رفت‌وبرگشت‌های ابزار قبل‌از شروع تولید، پیمایش در کلیپ‌های کوتاه (<۵ دقیقه) کمی «زمان تا اولین نشان» (TTFT) را افزایش دهد. پاسخ‌ها شامل MEDIA_PROCESSING بخش تماس ابزار و پاسخ است تا بافت استدلال در نوبت‌ها حفظ شود. بهترین گزینه برای ویدیوهای طولانی برای بهینه‌سازی هزینه داده‌واحد (توکن) و کیفیت پاسخ. در Gemini 3.8 Flash،‏ 3.6 Flash، و 3.5 Flash Lite پشتیبانی می‌شود. برای جزئیات بیشتر، درک ویدیو عامل‌دار را ببینید.
  • محاسبه نشان (حالت ایستا): هر ثانیه از ویدیو به‌صورت زیر نشان‌گذاری می‌شود:
    • فریم‌های تکی (نمونه‌برداری‌شده در ۱ فریم در ثانیه):
      • اگر 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) استفاده کنید. درخواست‌های هم‌زمان و غیرجاری‌سازی که در شرایط تقاضای بالا با تلاش مجدد زیرینه مواجه می‌شوند، ممکن است از پنجره‌های اعتبار اتصال یا رمز اصالت‌سنجی فراتر روند، که می‌تواند به‌صورت خطاهای غیرمنتظره 401 Unauthorized یا مهلت زمانی ظاهر شود. جاری‌سازی اتصال را فعال نگه می‌دارد و استدلال واسطه‌ای و پیشرفت تماس ابزار را نشان می‌دهد.

قدم بعدی چیست

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