فهم الفيديو

للتعرّف على ميزة إنشاء الفيديوهات، يُرجى الاطّلاع على دليل Veo.

يمكن لنماذج Gemini معالجة الفيديوهات، ما يتيح العديد من حالات استخدام المطوّرين المتقدّمة التي كانت تتطلّب في السابق نماذج خاصة بالمجال. تشمل بعض إمكانات Gemini في مجال الرؤية ما يلي: وصف الفيديوهات وتقسيمها واستخراج المعلومات منها، والإجابة عن الأسئلة حول محتوى الفيديو، والإشارة إلى طوابع زمنية محدّدة داخل الفيديو.

يمكنكم تقديم الفيديوهات كإدخال إلى Gemini بالطرق التالية:

طريقة الإرسال الحد الأقصى للحجم حالة الاستخدام المقترَحة
‫File API 20 غيغابايت (مدفوعة) / 2 غيغابايت (مجانية) الملفات الكبيرة (أكثر من 100 ميغابايت)، والفيديوهات الطويلة (أكثر من 10 دقائق)، والملفات القابلة لإعادة الاستخدام
تسجيل Cloud Storage 2 غيغابايت (لكل ملف، بدون حدود للتخزين) الملفات الكبيرة (أكثر من 100 ميغابايت)، والفيديوهات الطويلة (أكثر من 10 دقائق)، والملفات الثابتة القابلة لإعادة الاستخدام
البيانات المضمّنة أقل من 100 ميغابايت الملفات الصغيرة (أقل من 100 ميغابايت)، والفيديوهات القصيرة (أقل من دقيقة واحدة)، والمدخلات لمرة واحدة
عناوين URL على YouTube لا ينطبق الفيديوهات العلنية على YouTube

ملاحظة: ننصح باستخدام File API لمعظم حالات الاستخدام، خاصةً للملفات الأكبر من 100 ميغابايت أو عندما تريدون إعادة استخدام الملف في طلبات متعددة.

للتعرّف على طرق إدخال الملفات الأخرى، مثل استخدام عناوين URL خارجية أو ملفات مخزّنة في 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-flash-preview", 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-flash-preview",
    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-flash-preview",
    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-flash-preview: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 عندما يكون إجمالي حجم الطلب (بما في ذلك الملف والمطلوب النصي وتعليمات النظام وما إلى ذلك) أكبر من 20 ميغابايت، أو إذا كانت مدة الفيديو كبيرة، أو إذا كنتم تنوون استخدام الفيديو نفسه في طلبات متعددة. تقبل File API تنسيقات ملفات الفيديو مباشرةً.

لمزيد من المعلومات عن استخدام ملفات الوسائط، يُرجى الاطّلاع على Files API.

تمرير بيانات الفيديو مضمّنة

بدلاً من تحميل ملف فيديو باستخدام File API، يمكنكم تمرير فيديوهات أصغر حجمًا مباشرةً في الطلب إلى generateContent. هذا مناسب للفيديوهات القصيرة التي يقل إجمالي حجم الطلب فيها عن 20 ميغابايت.

في ما يلي مثال على تقديم بيانات فيديو مضمّنة:

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-flash-preview',
    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-flash-preview",
  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-flash-preview: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 على YouTube مباشرةً إلى Gemini API كجزء من طلبكم على النحو التالي:

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3-flash-preview',
    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-flash-preview",
  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-flash-preview",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

راحة

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview: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

القيود:

  • في المستوى المجاني، لا يمكنكم تحميل أكثر من 8 ساعات من فيديوهات YouTube في اليوم.
  • في المستوى المدفوع، لا يوجد حدّ أقصى استنادًا إلى مدة الفيديو.
  • بالنسبة إلى النماذج التي تسبق Gemini 2.5، لا يمكنكم تحميل سوى فيديو واحد لكل طلب. بالنسبة إلى Gemini 2.5 والنماذج الأحدث، يمكنكم تحميل 10 فيديوهات بحدّ أقصى لكل طلب.
  • لا يمكنكم تحميل سوى الفيديوهات العلنية (وليس الفيديوهات الخاصة أو غير المُدرَجة).

استخدام التخزين المؤقّت للسياق للفيديوهات الطويلة

بالنسبة إلى الفيديوهات التي تزيد مدتها عن 10 دقائق، أو عندما تخططون لإجراء طلبات متعددة على ملف الفيديو نفسه، استخدِموا التخزين المؤقّت للسياق لـ تقليل التكاليف وتحسين وقت الاستجابة. يتيح لكم التخزين المؤقّت للسياق معالجة الفيديو مرة واحدة وإعادة استخدام الرموز المميّزة للطلبات اللاحقة، ما يجعله مثاليًا لجلسات المحادثة أو التحليل المتكرّر للمحتوى الطويل.

الإشارة إلى الطوابع الزمنية في المحتوى

يمكنكم طرح أسئلة حول نقاط زمنية محدّدة داخل الفيديو باستخدام طوابع زمنية بالتنسيق MM:SS.

Python

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

JavaScript

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 إمكانات قوية لفهم محتوى الفيديو من خلال معالجة المعلومات من كلٍّ من المحتوى الصوتي والمرئي. يتيح لكم ذلك استخراج مجموعة كبيرة من التفاصيل، بما في ذلك إنشاء أوصاف لما يحدث في الفيديو والإجابة عن الأسئلة حول محتواه.

بالنسبة إلى الأوصاف المرئية، يختار النموذج عيّنات من الفيديو بمعدل إطار واحد في الثانية (FPS). يعمل معدّل اختيار العيّنات التلقائي هذا بشكل جيد لمعظم المحتوى، ولكن يُرجى العِلم أنّه قد لا يرصد التفاصيل في الفيديوهات التي تتضمّن حركة سريعة أو تغييرات سريعة في المشاهد. بالنسبة إلى هذا المحتوى الذي يتضمّن حركة سريعة، ننصحكم بضبط عدد اللقطات في الثانية المخصّص.

Python

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

JavaScript

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 مع إزاحتَي البدء والانتهاء.

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3-flash-preview',
    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-flash-preview';

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-flash-preview',
    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). قد تحتاجون إلى ضبط معدّل إطارات منخفض (< 1) للفيديوهات الطويلة. يفيد ذلك بشكل خاص في الفيديوهات الثابتة في الغالب (مثل المحاضرات). استخدِموا معدّل إطارات أعلى للفيديوهات التي تتطلب تحليلًا زمنيًا دقيقًا، مثل فهم الأحداث السريعة أو تتبُّع الحركة عالية السرعة.

تنسيقات الفيديو المتوافقة

يتوافق Gemini مع أنواع MIME لتنسيقات الفيديو التالية:

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

التفاصيل الفنية حول الفيديوهات

  • النماذج المتوافقة والسياق: يمكن لجميع نماذج Gemini معالجة بيانات الفيديو.
    • يمكن للنماذج التي تتضمّن قدرة استيعاب تبلغ مليون رمز مميّز معالجة فيديوهات تصل مدتها إلى ساعة واحدة بدقة الوسائط التلقائية أو 3 ساعات بدقة الوسائط المنخفضة.
  • معالجة File API: عند استخدام File API، يتم تخزين الفيديوهات بمعدّل إطار واحد في الثانية (FPS) وتتم معالجة المحتوى الصوتي بمعدّل 1 كيلوبت في الثانية (قناة واحدة). تتم إضافة الطوابع الزمنية كل ثانية.
    • من المحتمل أن تتغيّر هذه المعدّلات في المستقبل لتحسين الاستدلال.
    • يمكنكم تجاوز معدّل اختيار العيّنات البالغ إطارًا واحدًا في الثانية من خلال ضبط عدد اللقطات في الثانية المخصّص.
  • احتساب الرموز المميّزة: يتم تقسيم كل ثانية من الفيديو إلى رموز مميّزة على النحو التالي:
    • الإطارات الفردية (التي يتم اختيار عيّنات منها بمعدّل إطار واحد في الثانية):
      • إذا تم ضبط mediaResolution على منخفض، يتم تقسيم الإطارات إلى رموز مميّزة بمعدّل 66 رمزًا مميّزًا لكل إطار.
      • وإلا، يتم تقسيم الإطارات إلى رموز مميّزة بمعدّل 258 رمزًا مميّزًا لكل إطار.
    • المحتوى الصوتي: 32 رمزًا مميّزًا في الثانية
    • يتم تضمين البيانات الوصفية أيضًا.
    • الإجمالي: حوالي 300 رمز مميّز في الثانية من الفيديو بدقة الوسائط التلقائية، أو 100 رمز مميّز في الثانية من الفيديو بدقة الوسائط المنخفضة
  • دقة الوسائط: يقدّم Gemini 3 تحكّمًا دقيقًا في معالجة الرؤية المتعددة الوسائط باستخدام المَعلمة media_resolution. تحدّد المَعلمة media_resolution الحد الأقصى لعدد الرموز المميّزة المخصّصة لكل صورة إدخال أو إطار فيديو. تؤدي الدقة الأعلى إلى تحسين قدرة النموذج على قراءة النصوص الدقيقة أو تحديد التفاصيل الصغيرة، ولكنها تزيد من استخدام الرموز المميّزة ووقت الاستجابة.

    لمزيد من التفاصيل حول المَعلمة وكيفية تأثيرها في عمليات احتساب الرموز المميّزة ، يُرجى الاطّلاع على دليل دقة الوسائط.

  • تنسيق الطابع الزمني: عند الإشارة إلى لحظات محدّدة في فيديو ضمن طلبكم، استخدِموا الت2/} التنسيق (مثل 01:15 للدقيقة و15 ثانية).MM:SS

  • أفضل الممارسات:

    • استخدِموا فيديو واحدًا فقط لكل طلب للحصول على أفضل النتائج.
    • عند الجمع بين النص وفيديو واحد، ضَعوا المطلوب النصي بعد جزء الفيديو في مصفوفة contents.
    • يُرجى العِلم أنّ تسلسلات الأحداث السريعة قد تفقد التفاصيل بسبب معدّل اختيار العيّنات البالغ إطارًا واحدًا في الثانية. ننصحكم بإبطاء هذه المقاطع إذا لزم الأمر.

الخطوات التالية

يوضّح هذا الدليل كيفية تحميل ملفات الفيديو وإنشاء نصوص من مدخلات الفيديو. لمزيد من المعلومات، يُرجى الاطّلاع على المراجع التالية:

  • تعليمات النظام: تتيح لكم تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتكم وحالات استخدامكم المحدّدة.
  • واجهة برمجة تطبيقات الملفات: مزيد من المعلومات عن تحميل الملفات وإدارتها لاستخدامها مع Gemini.
  • استراتيجيات إنشاء الطلبات باستخدام الملفات: تتيح Gemini API إنشاء الطلبات باستخدام بيانات النص والصورة والصوت والفيديو، ويُعرف ذلك أيضًا باسم إنشاء الطلبات المتعددة الوسائط.
  • إرشادات الأمان: في بعض الأحيان، تُنتج نماذج الذكاء الاصطناعي التوليدي نتائج غير متوقّعة، مثل نتائج غير دقيقة أو متحيزة أو مسيئة. تُعدّ المعالجة اللاحقة والتقييم من قِبل فريق ضروريَين للحدّ من خطر الضرر الناتج عن هذه النتائج.