درک ویدیو
برای کسب اطلاعات در مورد تولید ویدیو، به راهنمای Veo مراجعه کنید.
مدلهای Gemini میتوانند ویدیوها را پردازش کنند و بسیاری از موارد استفاده توسعهدهندگان پیشرو را که از نظر تاریخی به مدلهای خاص دامنه نیاز داشتند، امکانپذیر سازند. برخی از قابلیتهای بینایی Gemini شامل توانایی توصیف، بخشبندی و استخراج اطلاعات از ویدیوها، پاسخ به سؤالات مربوط به محتوای ویدیو و ارجاع به مهرهای زمانی خاص در یک ویدیو است.
شما میتوانید ویدیوها را به روشهای زیر به عنوان ورودی به Gemini ارائه دهید:
| روش ورودی | حداکثر اندازه | مورد استفاده توصیه شده |
|---|---|---|
| API فایل | ۲۰ گیگابایت (پولی) / ۲ گیگابایت (رایگان) | فایلهای بزرگ (۱۰۰ مگابایت به بالا)، ویدیوهای طولانی (۱۰ دقیقه به بالا)، فایلهای قابل استفاده مجدد. |
| ثبت نام فضای ابری | ۲ گیگابایت (به ازای هر فایل، بدون محدودیت ذخیرهسازی) | فایلهای بزرگ (۱۰۰ مگابایت به بالا)، ویدیوهای طولانی (۱۰ دقیقه به بالا)، فایلهای ماندگار و قابل استفاده مجدد. |
| دادههای درونخطی | کمتر از ۱۰۰ مگابایت | فایلهای کوچک (کمتر از ۱۰۰ مگابایت)، مدت زمان کوتاه (کمتر از ۱ دقیقه)، ورودیهای یکباره. |
| آدرسهای اینترنتی یوتیوب | ناموجود | ویدیوهای عمومی یوتیوب. |
نکته: API فایل برای اکثر موارد استفاده توصیه میشود، به خصوص برای فایلهای بزرگتر از ۱۰۰ مگابایت یا زمانی که میخواهید از فایل در چندین درخواست دوباره استفاده کنید.
برای آشنایی با سایر روشهای ورودی فایل، مانند استفاده از URLهای خارجی یا فایلهای ذخیره شده در Google Cloud، به راهنمای روشهای ورودی فایل مراجعه کنید.
آپلود فایل ویدیویی
کد زیر یک ویدیوی نمونه را دانلود میکند، آن را با استفاده از API فایلها آپلود میکند، منتظر پردازش آن میماند و سپس از مرجع فایل آپلود شده برای خلاصه کردن ویدیو استفاده میکند.
پایتون
from google import genai
import base64
client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp4")
interaction = client.interactions.create(
model="gemini-3-flash-preview",
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.steps[-1].content[0].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 interaction = await ai.interactions.create({
model: "gemini-3-flash-preview",
input: [
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(interaction.steps.at(-1).content[0].text);
}
await main();
استراحت
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}"
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-flash-preview",
"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
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-flash-preview',
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.steps[-1].content[0].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-flash-preview",
input: [
{ type: "text", text: "Please summarize the video in 3 sentences." },
{
type: "video",
data: base64VideoFile,
mime_type: "video/mp4",
}
],
});
console.log(interaction.steps.at(-1).content[0].text);
استراحت
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-flash-preview",
"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-flash-preview',
input=[
{"type": "text", "text": "Please summarize the video in 3 sentences."},
{
"type": "video",
"uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
}
]
)
print(interaction.steps[-1].content[0].text)
جاوا اسکریپت
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-3-flash-preview",
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.steps.at(-1).content[0].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-flash-preview",
"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 و بالاتر، میتوانید حداکثر ۱۰ ویدیو در هر درخواست آپلود کنید.
- شما فقط میتوانید ویدیوهای عمومی (ویدیوهای خصوصی یا ویدیوهای ثبت نشده) را آپلود کنید.
به مهرهای زمانی در محتوا اشاره کنید
شما میتوانید با استفاده از مهرهای زمانی به شکل 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?";
استراحت
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.";
استراحت
PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."
فرمتهای ویدیویی پشتیبانیشده
Gemini از انواع MIME با فرمتهای ویدیویی زیر پشتیبانی میکند:
-
video/mp4 -
video/mpeg -
video/mov -
video/avi -
video/x-flv -
video/mpg -
video/webm -
video/wmv -
video/3gpp
جزئیات فنی در مورد ویدیوها
- مدلها و زمینههای پشتیبانیشده : همه Geminiها میتوانند دادههای ویدیویی را پردازش کنند.
- مدلهایی با پنجره زمینه ۱ مگابایتی میتوانند ویدیوهایی تا ۱ ساعت با وضوح رسانه پیشفرض یا ۳ ساعت با وضوح رسانه پایین را پردازش کنند.
- پردازش API فایل : هنگام استفاده از API فایل، ویدیوها با سرعت ۱ فریم در ثانیه (FPS) ذخیره میشوند و صدا با سرعت ۱ کیلوبیت بر ثانیه (تک کاناله) پردازش میشود. مهرهای زمانی هر ثانیه اضافه میشوند.
- این نرخها در آینده برای بهبود استنتاج قابل تغییر هستند.
- محاسبه توکن : هر ثانیه از ویدیو به صورت زیر توکنسازی میشود:
- فریمهای تکی (نمونهبرداری شده با سرعت ۱ فریم در ثانیه):
- اگر
media_resolutionروی مقدار پایین تنظیم شود، فریمها با ۶۶ توکن در هر فریم توکنسازی میشوند. - در غیر این صورت، فریمها با ۲۵۸ توکن در هر فریم توکنسازی میشوند.
- اگر
- صدا: ۳۲ توکن در ثانیه.
- متادیتا نیز گنجانده شده است.
- مجموع: تقریباً ۳۰۰ توکن در ثانیه ویدیو با وضوح رسانهای پیشفرض، یا ۱۰۰ توکن در ثانیه ویدیو با وضوح رسانهای پایین.
- فریمهای تکی (نمونهبرداری شده با سرعت ۱ فریم در ثانیه):
وضوح میانی : Gemini 3 با پارامتر
media_resolutionکنترل دقیقی بر پردازش بینایی چندوجهی ارائه میدهد. پارامترmedia_resolutionحداکثر تعداد توکنهای اختصاص داده شده به ازای هر تصویر یا فریم ویدیویی ورودی را تعیین میکند. وضوحهای بالاتر توانایی مدل را در خواندن متنهای ریز یا شناسایی جزئیات کوچک بهبود میبخشد، اما استفاده از توکن و تأخیر را افزایش میدهد.برای محاسبات، به راهنمای توکنها مراجعه کنید.
قالب مهر زمانی : هنگام اشاره به لحظات خاص در یک ویدیو در اعلان خود، از قالب
MM:SSاستفاده کنید (مثلاً01:15برای ۱ دقیقه و ۱۵ ثانیه).بهترین شیوهها :
- برای نتایج بهینه، فقط از یک ویدیو برای هر درخواست سریع استفاده کنید.
- اگر متن و یک ویدیو را با هم ترکیب میکنید، متن اعلان را بعد از بخش ویدیو در آرایه
inputقرار دهید. - توجه داشته باشید که سکانسهای اکشن سریع ممکن است به دلیل نرخ نمونهبرداری ۱ فریم در ثانیه جزئیات را از دست بدهند. در صورت لزوم، کاهش سرعت چنین کلیپهایی را در نظر بگیرید.
قدم بعدی چیست؟
این راهنما نحوه آپلود فایلهای ویدیویی و تولید خروجیهای متنی از ورودیهای ویدیویی را نشان میدهد. برای کسب اطلاعات بیشتر، به منابع زیر مراجعه کنید:
- دستورالعملهای سیستم : دستورالعملهای سیستم به شما امکان میدهند رفتار مدل را بر اساس نیازها و موارد استفاده خاص خود هدایت کنید.
- API فایلها : درباره آپلود و مدیریت فایلها برای استفاده با Gemini بیشتر بدانید.
- استراتژیهای اعلان فایل : رابط برنامهنویسی نرمافزار Gemini از اعلان با دادههای متنی، تصویری، صوتی و ویدیویی پشتیبانی میکند که به عنوان اعلان چندوجهی نیز شناخته میشود.
- راهنمایی ایمنی : گاهی اوقات مدلهای هوش مصنوعی مولد، خروجیهای غیرمنتظرهای مانند خروجیهای نادرست، جانبدارانه یا توهینآمیز تولید میکنند. پردازش پس از پردازش و ارزیابی انسانی برای محدود کردن خطر آسیب ناشی از چنین خروجیهایی ضروری است.