درک ویدیویی

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

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

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

قبل از شروع

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

ورودی ویدیو

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

یک فایل ویدئویی آپلود کنید

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

File API فرمت های فایل ویدیویی را مستقیماً می پذیرد. این مثال از فیلم کوتاه ناسا "لکه قرمز بزرگ مشتری کوچک می شود و رشد می کند" استفاده می کند. اعتبار: مرکز پرواز فضایی گدارد (GSFC)/دیوید لاد (2018).

"لکه قرمز بزرگ مشتری کوچک می شود و رشد می کند" در مالکیت عمومی است و افراد قابل شناسایی را نشان نمی دهد. ( دستورالعمل‌های استفاده از تصویر و رسانه ناسا. )

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

پایتون

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

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

response = client.models.generate_content(
    model="gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });

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

برو

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

استراحت

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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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 مراجعه کنید.

داده‌های ویدیویی را به‌خط ارسال کنید

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

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

پایتون

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

response = client.models.generate_content(
    model='models/gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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.0-flash:generateContent?key=$GOOGLE_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

آدرس یوتیوب را اضافه کنید

Gemini API و AI Studio از URLهای یوتیوب به عنوان Part داده فایل پشتیبانی می کنند. می‌توانید یک URL YouTube با درخواستی که از مدل می‌خواهد خلاصه کند، ترجمه کند یا با محتوای ویدیویی تعامل داشته باشد، اضافه کنید.

محدودیت ها:

  • شما نمی توانید بیش از 8 ساعت ویدیوی YouTube در روز آپلود کنید.
  • در هر درخواست فقط 1 ویدیو می توانید آپلود کنید.
  • شما فقط می توانید ویدیوهای عمومی (نه ویدیوهای خصوصی یا فهرست نشده) را آپلود کنید.

مثال زیر نشان می دهد که چگونه یک URL YouTube را با یک درخواست اضافه کنید:

پایتون

response = client.models.generate_content(
    model='models/gemini-2.0-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-1.5-pro" });
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());

برو

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
  genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
  genai.Text("Please summarize the video in 3 sentences."))
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text.
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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

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

می‌توانید با استفاده از مهرهای زمانی به شکل 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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
         // Adjusted timestamps for the NASA video
        genai.Text("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 می‌توانند با پردازش تراک صوتی و فریم‌های بصری، محتوای ویدیویی را رونویسی کرده و توضیحات بصری ارائه دهند. برای توصیف بصری، مدل ویدئو را با سرعت 1 فریم در ثانیه نمونه برداری می کند. این نرخ نمونه‌برداری ممکن است بر سطح جزئیات در توضیحات تأثیر بگذارد، به‌ویژه برای ویدیوهایی با تغییرات بصری سریع.

پایتون

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

جاوا اسکریپت

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

برو

    prompt := []genai.Part{
        genai.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
        genai.Text("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

استراحت

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

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

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 می‌توانند داده‌های ویدیویی را پردازش کنند.
    • مدل‌های دارای پنجره زمینه 2M می‌توانند ویدیوهای تا 2 ساعت را پردازش کنند، در حالی که مدل‌هایی با پنجره زمینه 1M می‌توانند ویدیوهای حداکثر 1 ساعت را پردازش کنند.
  • پردازش File API : هنگام استفاده از File API، ویدیوها با سرعت 1 فریم در ثانیه (FPS) نمونه برداری می شوند و صدا با سرعت 1Kbps (تک کانال) پردازش می شود. هر ثانیه مهر زمانی اضافه می شود.
    • این نرخ‌ها در آینده برای بهبود استنتاج ممکن است تغییر کنند.
  • محاسبه توکن : هر ثانیه از ویدیو به صورت زیر نشانه گذاری می شود:
    • فریم‌های مجزا (نمونه‌برداری شده با 1 فریم در ثانیه): 258 توکن در هر فریم.
    • صدا: 32 توکن در ثانیه.
    • متادیتا نیز گنجانده شده است.
    • مجموع: تقریباً 300 توکن در هر ثانیه ویدیو.
  • قالب مهر زمان : وقتی به لحظات خاصی در یک ویدیو در درخواست خود اشاره می کنید، از قالب MM:SS استفاده کنید (مثلاً 01:15 به مدت 1 دقیقه و 15 ثانیه).
  • بهترین شیوه ها :
    • برای نتایج بهینه در هر درخواست فوری فقط از یک ویدیو استفاده کنید.
    • اگر متن و یک ویدیو را با هم ترکیب می کنید، اعلان متن را بعد از قسمت ویدیو در آرایه contents قرار دهید.
    • توجه داشته باشید که توالی‌های اقدام سریع ممکن است به دلیل نرخ نمونه‌برداری 1 FPS جزئیات را از دست بدهند. در صورت لزوم، سرعت چنین کلیپ هایی را کاهش دهید.

بعدش چی

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

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