درک ویدیویی

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

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

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

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

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

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

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

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

پایتون

from google import genai
import time

client = genai.Client()

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

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

جاوا اسکریپت

import { GoogleGenAI } 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" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

استراحت

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)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "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 ".steps[].content[0].text" response.json

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

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

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

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

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

پایتون

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

استراحت

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null

URL های YouTube را منتقل کنید

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

پایتون

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

جاوا اسکریپت

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "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 همچنین از درک عامل‌مند ویدیو پشتیبانی می‌کنند، که در آن مدل به صورت پویا جدول زمانی ویدیو را بررسی می‌کند، رونوشت‌ها را به صورت انتخابی بررسی می‌کند و نرخ فریم و وضوح را به صورت تطبیقی ​​​​در لحظه بر اساس درخواست تنظیم می‌کند.

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

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

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

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

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

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

پایتون

import time
from google import genai

client = genai.Client()

# Upload a long video
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)

# Use agentic processing
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ]
)
print(interaction.output_text)

جاوا اسکریپت

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

const ai = new GoogleGenAI({});

// Upload a long video
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 });
}

// Use agentic processing
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ]
});
console.log(interaction.output_text);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ]
  }' 2> /dev/null

نکته: برای تأیید اینکه از پردازش عامل‌محور استفاده شده است، interaction.steps را بررسی کنید. وجود processing_call و processing_result نشان می‌دهد که مدل به صورت پویا ویدیو را پیمایش کرده است.

مراحل پاسخ

پردازش عامل‌محور دو نوع گام جدید به آرایه steps اضافه می‌کند:

  • processing_call : مدل یک بخش ویدیویی یا رونوشت صوتی را درخواست کرده است که با id مشخص شده است.
  • processing_result : نتیجه‌ی آن بارگذاری، که توسط call_id لینک شده است.

این موارد (در صورت فعال بودن خلاصه‌ها) در میان مراحل thought ظاهر می‌شوند و قبل از مرحله نهایی model_output قرار می‌گیرند. آن‌ها می‌توانند برای نمایش ردیابی پیشرفت در رابط کاربری شما استفاده شوند، اما نیازی به پاسخ ندارند.

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

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

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

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

پایتون

from google import genai

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ]
});
console.log(interaction.output_text);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
  }' 2> /dev/null

مکالمات ویدیویی چند نوبتی

متن ویدیو در طول مکالمه حفظ می‌شود. هنگام استفاده از پردازش عاملی:

  • حالت با وضعیت (با استفاده از previous_interaction_id ): سرور محتوای ویدیو را حفظ می‌کند. نیازی به دستکاری اضافی نیست.
  • حالت بدون وضعیت (با استفاده از step_list ): در حالت بدون وضعیت، پاسخ شامل مراحل processing_call و processing_result است که زمینه ویدیو را رمزگذاری می‌کنند. شما باید تمام مراحل پاسخ را در step_list درخواست بعدی خود قرار دهید تا زمینه ویدیو حفظ شود. اگرچه حذف آنها در حال حاضر خطای API را برنمی‌گرداند، اما زمینه ویدیو از بین می‌رود و کیفیت پاسخ را در سوالات بعدی به طور قابل توجهی کاهش می‌دهد. توجه داشته باشید که مراحل بازگشتی ارسال شده در درخواست‌های بعدی به تعداد توکن‌های ورودی کمک می‌کنند.

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

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

پایتون

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

جاوا اسکریپت

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

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

استراحت

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.";

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

استراحت

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

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

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

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

شما می‌توانید با مشخص کردن start_offset و end_offset در شیء پیکربندی processing ویدیو را برش دهید.

پایتون

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

جاوا اسکریپت

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

تنظیم نرخ فریم سفارشی

شما می‌توانید با ارسال آرگومان fps در شیء پیکربندی processing نمونه‌برداری نرخ فریم سفارشی را تنظیم کنید.

پایتون

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

جاوا اسکریپت

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

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

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

  • video/mp4
  • video/mpeg
  • video/mov
  • 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) را در کلیپ‌های کوتاه (کمتر از ۵ دقیقه) کمی افزایش دهد. بهترین گزینه برای ویدیوهای طولانی برای بهینه‌سازی هزینه‌های توکن و کیفیت پاسخ. پشتیبانی شده در Gemini 3.8 Flash، 3.7 Flash، 3.6 Flash و 3.5 Flash Lite. برای جزئیات بیشتر به بخش درک ویدیوی Agentic مراجعه کنید.
  • محاسبه توکن (حالت استاتیک) : هر ثانیه از ویدیو به صورت زیر توکن‌سازی می‌شود:
    • فریم‌های تکی (نمونه‌برداری شده با سرعت ۱ فریم در ثانیه):
      • اگر media_resolution روی مقدار پایین تنظیم شود، فریم‌ها با ۶۶ توکن در هر فریم توکن‌سازی می‌شوند.
      • در غیر این صورت، فریم‌ها با ۲۵۸ توکن در هر فریم توکن‌سازی می‌شوند.
    • صدا: ۳۲ توکن در ثانیه.
    • متادیتا نیز گنجانده شده است.
    • مجموع: تقریباً ۱۰۰ توکن در ثانیه از ویدیو با وضوح رسانه‌ای پیش‌فرض (پایین)، یا تقریباً ۳۰۰ توکن در ثانیه از ویدیو با وضوح رسانه‌ای بالا.
  • محاسبه توکن (حالت عامل) : میزان استفاده از توکن بر اساس پیچیدگی محتوا و استراتژی ناوبری مدل متفاوت است. توکن‌های استدلال ناوبری که در طول کاوش ویدیو تولید می‌شوند، به عنوان توکن‌های فکری ( total_thought_tokens ) در نظر گرفته می‌شوند، در حالی که فریم‌ها، صدا و متن بارگذاری شده بر اساس تقاضا، به عنوان توکن‌های استفاده از ابزار ( total_tool_use_tokens ) در نظر گرفته می‌شوند. پردازش عامل معمولاً تا ۸۸٪ توکن‌های کمتری نسبت به پردازش استاتیک برای محتوای طولانی استفاده می‌کند، زیرا مدل فقط رونوشت و/یا فریم‌ها و/یا صوتی را که برای پاسخ به سوال نیاز دارد، بارگذاری می‌کند (به راهنمای توکن‌ها مراجعه کنید).
  • وضوح رسانه : Gemini 3 با پارامتر media_resolution کنترل دقیقی بر پردازش بینایی چندوجهی ارائه می‌دهد. پارامتر media_resolution حداکثر تعداد توکن‌های اختصاص داده شده به ازای هر تصویر ورودی یا فریم ویدیو را تعیین می‌کند. وضوح‌های بالاتر توانایی مدل را در خواندن متن ریز یا شناسایی جزئیات کوچک بهبود می‌بخشند، اما استفاده از توکن و تأخیر را افزایش می‌دهند. پارامترهای media_resolution و processing مستقل هستند: می‌توانید هر دو را روی یک ورودی ویدیو تنظیم کنید.

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

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

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

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