درک ویدیو

برای آشنایی با تولید ویدیو، راهنمای 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())

استراحت

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 استفاده کنید. «میانای برنامه‌سازی کاربردی فایل» قالب‌های فایل ویدیویی را مستقیماً می‌پذیرد.

برای کسب اطلاعات بیشتر درباره کار با فایل‌های رسانه‌ای، 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);

استراحت

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

استراحت

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 4، استفاده می‌کنند. مدل‌های Gemini 4 Argon،‏ 3.8 Flash،‏ 3.6 Flash، و 3.5 Flash Lite از درک ویدیو عاملی نیز پشتیبانی می‌کنند، حالتی اختیاری که در آن مدل به‌طور پویا خط زمان ویدیو را کاوش می‌کند، رونویسی‌ها را به‌طور انتخابی بررسی می‌کند، و نرخ فریم و وضوح را به‌طور تطبیقی و درلحظه براساس پیام‌واره تنظیم می‌کند.

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

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

حالت پردازشی را که با طول ویدیو و نوع پُرسمان شما مطابقت دارد انتخاب کنید:

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

توجه: برای ویدیوهای طولانی یا پیام‌واره‌های پیچیده که پردازش عاملی زمان بیشتری می‌برد، از جاری‌سازی (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())

استراحت

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

استراحت

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