درک ویدیویی

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

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

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

ورودی ویدئو

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

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

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

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

پایتون

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

جاوا اسکریپت

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

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

  const response = await ai.models.generateContent({
    model: "gemini-2.5-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-2.5-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-2.5-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 مراجعه کنید.

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

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

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

پایتون

from google import genai
from google.genai import types

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

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

جاوا اسکریپت

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-2.5-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-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"video/mp4",
                "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'"
              }
            },
            {"text": "Please summarize the video in 3 sentences."}
        ]
      }]
    }' 2> /dev/null

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

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

پایتون

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

جاوا اسکریپت

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.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-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {"text": "Please summarize the video in 3 sentences."},
            {
              "file_data": {
                "file_uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
              }
            }
        ]
      }]
    }' 2> /dev/null

محدودیت‌ها:

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

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

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

پایتون

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

جاوا اسکریپت

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

برو

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

استراحت

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

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

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

پایتون

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

جاوا اسکریپت

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

برو

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

استراحت

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

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

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

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

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

پایتون

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

جاوا اسکریپت

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-2.5-flash';

async function main() {
const contents = [
  {
    role: 'user',
    parts: [
      {
        fileData: {
          fileUri: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mimeType: 'video/*',
        },
        videoMetadata: {
          startOffset: '40s',
          endOffset: '80s',
        }
      },
      {
        text: 'Please summarize the video in 3 sentences.',
      },
    ],
  },
];

const response = await ai.models.generateContent({
  model,
  contents,
});

console.log(response.text)

}

await main();

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

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

پایتون

from google import genai
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

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

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

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

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

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

  • مدل‌ها و زمینه‌های پشتیبانی‌شده : همه مدل‌های Gemini 2.0 و 2.5 می‌توانند داده‌های ویدیویی را پردازش کنند.
    • مدل‌هایی با پنجره زمینه ۲ مگابایتی می‌توانند ویدیوهایی تا ۲ ساعت با وضوح رسانه پیش‌فرض یا ۶ ساعت با وضوح رسانه پایین را پردازش کنند، در حالی که مدل‌هایی با پنجره زمینه ۱ مگابایتی می‌توانند ویدیوهایی تا ۱ ساعت با وضوح رسانه پیش‌فرض یا ۳ ساعت با وضوح رسانه پایین را پردازش کنند.
  • پردازش API فایل : هنگام استفاده از API فایل، ویدیوها با سرعت ۱ فریم در ثانیه (FPS) ذخیره می‌شوند و صدا با سرعت ۱ کیلوبیت بر ثانیه (تک کاناله) پردازش می‌شود. مهرهای زمانی هر ثانیه اضافه می‌شوند.
    • این نرخ‌ها در آینده برای بهبود استنتاج قابل تغییر هستند.
    • شما می‌توانید با تنظیم یک نرخ فریم سفارشی، نرخ نمونه‌برداری ۱ فریم بر ثانیه را نادیده بگیرید.
  • محاسبه توکن : هر ثانیه از ویدیو به صورت زیر توکن‌سازی می‌شود:
    • فریم‌های تکی (نمونه‌برداری شده با سرعت ۱ فریم در ثانیه):
      • اگر mediaResolution روی مقدار پایین تنظیم شده باشد، فریم‌ها با ۶۶ توکن در هر فریم توکن‌سازی می‌شوند.
      • در غیر این صورت، فریم‌ها با ۲۵۸ توکن در هر فریم توکن‌سازی می‌شوند.
    • صدا: ۳۲ توکن در ثانیه.
    • متادیتا نیز گنجانده شده است.
    • مجموع: تقریباً ۳۰۰ توکن در ثانیه ویدیو با وضوح رسانه‌ای پیش‌فرض، یا ۱۰۰ توکن در ثانیه ویدیو با وضوح رسانه‌ای پایین.
  • قالب مهر زمانی : هنگام اشاره به لحظات خاص در یک ویدیو در اعلان خود، از قالب MM:SS استفاده کنید (مثلاً 01:15 برای ۱ دقیقه و ۱۵ ثانیه).
  • بهترین شیوه‌ها :
    • برای نتایج بهینه، فقط از یک ویدیو برای هر درخواست سریع استفاده کنید.
    • اگر متن و یک ویدیو را با هم ترکیب می‌کنید، متن اعلان را بعد از بخش ویدیو در آرایه contents قرار دهید.
    • توجه داشته باشید که سکانس‌های اکشن سریع ممکن است به دلیل نرخ نمونه‌برداری ۱ فریم در ثانیه جزئیات را از دست بدهند. در صورت لزوم، کاهش سرعت چنین کلیپ‌هایی را در نظر بگیرید.

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

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

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