فهم الفيديو

لمزيد من المعلومات حول إنشاء الفيديوهات، يمكنك الاطّلاع على دليل Gemini Omni Flash.

يمكن لنماذج 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.8-flash", 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.8-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();

Go

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.8-flash",
    contents,
    nil,
)

fmt.Println(result.Text())

REST

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.8-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 عندما يكون الحجم الإجمالي للطلب (بما في ذلك الملف، والنص المطلوب، وتعليمات النظام، وما إلى ذلك) أكبر من 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.8-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.')
        ]
    )
)
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.8-flash",
  contents: contents,
});
console.log(response.text);

REST

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

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-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.')
        ]
    )
)
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.8-flash",
  contents: contents,
});
console.log(response.text);

Go

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.8-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

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

القيود:

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

فهم الفيديوهات المستند إلى الذكاء الاصطناعي الوكيل

تستخدم مدخلات الفيديو تلقائيًا معالجة ثابتة (استخراج اللقطات بمعدل لقطة واحدة في الثانية). تتيح نماذج Gemini 3.8 Flash و3.7 Flash و3.6 Flash و3.5 Flash Lite أيضًا ميزة الفهم الآلي للفيديوهات، حيث يستكشف النموذج المخطط الزمني للفيديو بشكل ديناميكي، ويفحص النصوص بشكل انتقائي، ويعدّل معدّل عرض اللقطات ودرجة الدقة بشكل تكيفي أثناء التشغيل استنادًا إلى الطلب.

الوضع الوصف الطُرز المتوافقة
ثابتة (تلقائي) يستخرج اللقطات بمعدّل ثابت (لقطة واحدة في الثانية) ويضعها في السياق في عملية واحدة. مناسبة للمقاطع القصيرة جميع نماذج Gemini
Agentic يتنقّل النموذج ديناميكيًا في المخطط الزمني للفيديو، ولا يحمّل سوى المحتوى الذي يحتاجه استنادًا إلى الطلب. زيادة في كفاءة استخدام الرموز المميزة بنسبة تصل إلى% 88 وتحسين جودة المحتوى الطويل بنسبة% 7 تقريبًا ‫Gemini 3.8 Flash و3.7 Flash و3.6 Flash و3.5 Flash Lite

اختيار وضع المعالجة

كإرشادات عامة، ننصحك بالبدء باستخدام الوضع الوكيل، خاصةً عند تحسين جودة الردود أو كفاءة الرموز المميزة.

  • الاستجابة المباشرة: فيديوهات طويلة أو طلبات بحث تستهدف لحظات معيّنة يتنقّل النموذج بشكل ديناميكي في المخطط الزمني لاستهداف المعلومات ذات الصلة بالسياق بدون ملء نافذة السياق.
  • ثابتة: طلبات البحث التي تتطلّب سرعة استجابة عالية على مقاطع قصيرة (أقل من 5 دقائق)، أو الحالات التي تتطلّب دقة على مستوى الإطار في المقطع بأكمله.

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

ضبط وضع المعالجة

Python

import time
from google import genai
from google.genai import types

client = genai.Client()

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)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_file.uri,
            mime_type=video_file.mime_type,
            media_processing="AGENTIC",
        ),
        "What are the three main arguments presented?",
    ],
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

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 });
}

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: videoFile.uri,
            mimeType: videoFile.mimeType,
          },
          mediaProcessing: "AGENTIC",
        },
        { text: "What are the three main arguments presented?" },
      ],
    },
  ],
});
console.log(response.text);

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/lecture.mp4", nil)
parts := []*genai.Part{
    {
        FileData: &genai.FileData{
            FileURI:  uploadedFile.URI,
            MIMEType: uploadedFile.MIMEType,
        },
        MediaProcessing: genai.MediaProcessingAgentic,
    },
    genai.NewPartFromText("What are the three main arguments presented?"),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${file_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {"text": "What are the three main arguments presented?"}
      ]
    }]
  }'

ملاحظة: للتأكّد من استخدام المعالجة المستندة إلى الوكيل، افحص response.candidates[0].content.parts. يشير توفّر الأجزاء tool_call وtool_response مع نوع الأداة MEDIA_PROCESSING إلى أنّ النموذج تنقّل ديناميكيًا في الفيديو.

ملاحظة: بخلاف الأدوات الأخرى من جهة الخادم (مثل &quot;بحث Google&quot; أو سياق عنوان URL)، لا تتطلّب ميزة &quot;الفيديو المستند إلى الذكاء الاصطناعي التوليدي&quot; ضبط include_server_side_tool_invocations=True في ToolConfig لكي يتم عرض نتائج الأدوات أو بثها. يتم عرض الجزءَين tool_call وtool_response الخاصَين بالتنقّل في الفيديو تلقائيًا عند ضبط media_processing="AGENTIC" على أي جزء من الإدخال.

بنية الردّ

عند تفعيل المعالجة المستندة إلى الوكيل، يتضمّن الردّ أجزاءً إضافية تعرض مسار التنقّل الداخلي:

  • tool_call الأجزاء (tool_type: "MEDIA_PROCESSING"): يتم إرسالها في كل مرة يطلب فيها النموذج مقطع فيديو أو نصًا صوتيًا.
  • tool_response الأجزاء (tool_type: "MEDIA_PROCESSING"): نتيجة كل عملية تحميل

لست بحاجة إلى التعامل مع هذه الأجزاء أو الردّ عليها يدويًا: ما عليك سوى إعادة الردّ الكامل كسجلّ محادثات، وسيتم التعامل معها تلقائيًا.

إذا تم ضبط include_thoughts=True في ThinkingConfig، ستظهر خطوات الاستدلال كأجزاء thought: true متداخلة مع أزواج طلب/ردّ الأداة. عند إيقاف الأفكار، يتم حذف نص الفكرة ولكن تبقى أجزاء الأداة متوفّرة.

يعرض المثال التالي حمولة الاستجابة مع أجزاء متداخلة من طلب الأداة والاستجابة:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "thought": true,
            "text": "Inspecting transcript for key discussion topics..."
          },
          {
            "thought_signature": "sig_A",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_B",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Loading visual frames to verify slide content..."
          },
          {
            "thought_signature": "sig_C",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_D",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Synthesizing answer from gathered evidence..."
          },
          {
            "text": "The three main arguments presented in the lecture are...",
            "thought_signature": "sig_E"
          }
        ]
      }
    }
  ]
}

استخدام أوضاع معالجة مختلفة في فيديوهات متعددة

يمكنك ضبط أوضاع معالجة مختلفة لكل جزء من الفيديو في الطلب نفسه:

Python

from google import genai
from google.genai import types

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",  # Use agentic video understanding
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",  # Use static processing
        ),
        "Compare the lecture content with the experiment results.",
    ],
)
print(response.text)

JavaScript

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 response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: lecture.uri,
            mimeType: lecture.mimeType,
          },
          mediaProcessing: "AGENTIC", // Use agentic video understanding
        },
        {
          fileData: {
            fileUri: experiment.uri,
            mimeType: experiment.mimeType,
          },
          mediaProcessing: "STATIC", // Use static processing
        },
        { text: "Compare the lecture content with the experiment results." },
      ],
    },
  ],
});
console.log(response.text);

Go

lecturePart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  lectureFile.URI,
        MIMEType: lectureFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingAgentic, // Use agentic
}
experimentPart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  experimentFile.URI,
        MIMEType: experimentFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingStatic, // Use static
}
parts := []*genai.Part{
    lecturePart,
    experimentPart,
    genai.NewPartFromText("Compare the lecture content with the experiment results."),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${lecture_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {
          "file_data": {
            "file_uri": "'${experiment_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "STATIC"
        },
        {"text": "Compare the lecture content with the experiment results."}
      ]
    }]
  }'

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

بالنسبة إلى الفيديوهات التي تزيد مدتها عن 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?";

Go

    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?"),
    }

REST

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

Go

    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."),
    }

REST

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

تخصيص معالجة الفيديو

يمكنك تخصيص معالجة الفيديو في Gemini API من خلال ضبط فواصل زمنية لتقطيع الفيديو أو تقديم عيّنات مخصّصة لمعدّل عرض اللقطات. لا تتوفّر خيارات التخصيص هذه إلا عند معالجة الفيديو في وضع "static".

ضبط الفواصل الزمنية لقص الفيديو

يمكنك قص الفيديو من خلال تحديد videoMetadata مع إزاحة البدء والانتهاء.

Python

from google import genai
from google.genai import types

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

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.8-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.

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

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

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

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

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

  • النماذج المتوافقة والسياق: يمكن لجميع نماذج Gemini معالجة بيانات الفيديو.
    • يمكن للنماذج التي تتضمّن قدرة استيعاب مليون رمز مميّز معالجة فيديوهات تصل مدتها إلى 3 ساعات تلقائيًا (بدقة وسائط منخفضة)، أو فيديوهات تصل مدتها إلى ساعة واحدة بدقة وسائط عالية.
  • طرق المعالجة: تتوافق نماذج Gemini 3.8 Flash و3.7 Flash و3.6 Flash و3.5 Flash Lite والنماذج الأحدث مع طريقتَين لمعالجة الفيديوهات:
    • ثابتة: يتم استخراج اللقطات بمعدّل لقطة واحدة في الثانية ووضعها في السياق (الإعداد التلقائي لجميع النماذج). تتم معالجة الصوت بمعدل 1 كيلوبت في الثانية (قناة واحدة). تتم إضافة الطوابع الزمنية كل ثانية. هذا الخيار هو الأفضل للمقاطع القصيرة أو عندما تكون كل لقطة مهمة (مثل الفحص لقطة بلقطة). يُرجى العِلم أنّ تسلسلات الإجراءات السريعة قد تفقد بعض التفاصيل بسبب معدّل أخذ العيّنات البالغ إطارًا واحدًا في الثانية.
    • التفاعلية: يتنقّل النموذج ديناميكيًا في الفيديو، ويحمّل النص و/أو اللقطات و/أو الصوت عند الطلب. يستخدم هذا النموذج عددًا أقل من الرموز المميزة بنسبة تصل إلى %88 للمحتوى الطويل، ولكن قد تزيد مدة TTFT قليلاً في المقاطع القصيرة (أقل من 5 دقائق) بسبب عمليات الاستدلال الداخلية والرحلات المتكررة للأداة قبل بدء عملية الإنشاء. تتضمّن الردود أجزاء MEDIA_PROCESSING لطلب استخدام الأداة والردّ عليها للحفاظ على سياق الاستدلال في مختلف مراحل المحادثة. الأفضل للفيديوهات الطويلة لتحسين تكاليف الرموز المميزة وجودة الردود متوافق مع Gemini 3.8 Flash و3.7 Flash و3.6 Flash و3.5 Flash Lite يمكنك الاطّلاع على مقالة فهم الفيديو المستند إلى الذكاء الاصطناعي لمعرفة التفاصيل.
  • احتساب الرموز المميزة (الوضع الثابت): يتم تقسيم كل ثانية من الفيديو إلى رموز مميزة على النحو التالي:
    • اللقطات الفردية (يتم أخذ عينات بمعدل لقطة واحدة في الثانية):
      • إذا تم ضبط media_resolution على "منخفض"، يتم تقسيم اللقطات إلى 66 رمزًا مميزًا لكل لقطة.
      • بخلاف ذلك، يتم تقسيم اللقطات إلى رموز مميزة بمعدل 258 رمزًا مميزًا لكل لقطة.
    • الصوت: 32 رمزًا مميزًا في الثانية
    • يتم تضمين البيانات الوصفية أيضًا.
    • الإجمالي: حوالي 100 رمز مميز لكل ثانية من الفيديو بدقة الوسائط التلقائية (المنخفضة)، أو حوالي 300 رمز مميز لكل ثانية من الفيديو بدقة الوسائط العالية
  • احتساب الرموز المميزة (الوضع التفاعلي): يختلف استخدام الرموز المميزة حسب مدى تعقيد المحتوى واستراتيجية التنقّل في النموذج. يتم احتساب الرموز المميزة الخاصة بالاستدلال على التنقّل التي يتم إنشاؤها أثناء استكشاف الفيديو ضمن رموز التفكير (thoughts_token_count)، بينما يتم احتساب الإطارات والصوت والنصوص التي يتم تحميلها عند الطلب ضمن رموز طلب الأداة (tool_use_prompt_token_count). تستخدم المعالجة المستندة إلى الوكيل عادةً عددًا أقل من الرموز المميزة الإجمالية بنسبة تصل إلى% 88 مقارنةً بالمعالجة الثابتة للمحتوى الطويل، لأنّ النموذج يحمّل فقط النص و/أو الإطارات و/أو الصوت الذي يحتاج إليه للإجابة عن الطلب (راجِع دليل الرموز المميزة).
  • دقة الوسائط: يتيح Gemini 3 التحكّم بدقة في معالجة الصور المتعددة الوسائط باستخدام المَعلمة media_resolution. تحدّد المَعلمة media_resolution الحدّ الأقصى لعدد الرموز المميزة المخصّصة لكل صورة إدخال أو إطار فيديو. تساهم الدقة الأعلى في تحسين قدرة النموذج على قراءة النصوص الدقيقة أو تحديد التفاصيل الصغيرة، ولكنها تزيد من استخدام الرموز المميزة ووقت الاستجابة. المَعلمتان media_resolution وmedia_processing مستقلّتان، ويمكنك ضبطهما معًا في جزء الفيديو نفسه.

لمزيد من التفاصيل حول عمليات حساب الرموز المميزة، راجِع دليل الرموز المميزة.

  • تنسيق الطابع الزمني: عند الإشارة إلى لحظات معيّنة في فيديو ضمن طلبك، استخدِم التنسيق MM:SS (مثلاً، 01:15 للإشارة إلى دقيقة واحدة و15 ثانية).
  • موضع الطلب: في حال الجمع بين نص وفيديو واحد، ضَع طلب النص بعد جزء الفيديو في مصفوفة contents.
  • انتهاء المهلة للطلبات الطويلة: بالنسبة إلى الفيديوهات التي تتطلّب وقت معالجة أطول أو تتضمّن الاستدلال المتعدّد الخطوات المعقّد، استخدِم البث (client.models.generate_content_stream). يمكن أن تتجاوز الطلبات المتزامنة وغير المتعلّقة بالبث والتي تتم إعادة محاولتها في الخلفية بسبب ارتفاع الطلب، مدة صلاحية الاتصال أو رمز المصادقة المميز، ما قد يؤدي إلى ظهور أخطاء 401 Unauthorized أو أخطاء انتهاء المهلة غير متوقّعة. يؤدي البث إلى إبقاء الاتصال نشطًا وعرض عملية الاستدلال المرحلية وتقدّم عملية استدعاء الأداة.

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

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