فهم الفيديو

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

  • وصف الفيديوهات وتقسيمها واستخراج المعلومات منها
  • الإجابة عن أسئلة حول محتوى الفيديو
  • الإشارة إلى طوابع زمنية محدّدة في فيديو

تم تصميم Gemini ليكون متعدّد الوسائط منذ البداية، ونواصل توسيع حدود ما يمكن تحقيقه. يوضّح هذا الدليل كيفية استخدام Gemini API لإنشاء ردود نصية استنادًا إلى مدخلات الفيديو.

إدخال الفيديو

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

  • حمِّل ملف فيديو باستخدام File API قبل إرسال طلب إلى generateContent. استخدِم هذه الطريقة للملفات التي يزيد حجمها عن 20 ميغابايت أو الفيديوهات التي تزيد مدتها عن دقيقة واحدة تقريبًا، أو عندما تريد إعادة استخدام الملف في طلبات متعددة.
  • تمرير بيانات الفيديو المضمّن مع الطلب إلى generateContent استخدِم هذه الطريقة للملفات الأصغر حجمًا (أقل من 20 ميغابايت) والمدد الأقصر.
  • أدرِج عنوان URL لفيديو على YouTube مباشرةً في الطلب.

تحميل ملف فيديو

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

ينزّل الرمز التالي الفيديو النموذجي، ويحمّله باستخدام File API، وينتظر إلى أن تتم معالجته، ثم يستخدم مرجع الملف في طلب generateContent.

Python

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)

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-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())

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

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

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

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

Python

# 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.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.')
        ]
    )
)

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-2.5-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-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

تتيح واجهة Gemini API وAI Studio استخدام عناوين URL على YouTube كبيانات ملف Part. يمكنك تضمين عنوان URL لفيديو على YouTube مع طلب موجّه إلى النموذج لتلخيص محتوى الفيديو أو ترجمته أو التفاعل معه بأي طريقة أخرى.

القيود:

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

يوضّح المثال التالي كيفية تضمين عنوان URL على YouTube مع طلب:

Python

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.')
        ]
    )
)

JavaScript

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

انتقال

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

REST

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

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

يمكنك طرح أسئلة حول نقاط زمنية محدّدة في الفيديو باستخدام الطوابع الزمنية بالتنسيق 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?"),
    }

REST

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

تحويل الفيديو إلى نص وتقديم أوصاف مرئية

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

Python

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

JavaScript

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

انتقال

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

REST

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

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

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

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

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

Python

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.')
        ]
    )
)

ضبط معدّل لقطات مخصّص في الثانية

يمكنك ضبط معدّل أخذ العيّنات المخصّص لعدد اللقطات في الثانية من خلال تمرير وسيطة fps إلى videoMetadata.

Python

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

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

يتوافق 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 معالجة بيانات الفيديو.
    • يمكن لنماذج ذات سعة سياق تبلغ مليوني رمز مميّز معالجة فيديوهات تصل مدتها إلى ساعتين بدقة الوسائط التلقائية أو 6 ساعات بدقة الوسائط المنخفضة، بينما يمكن لنماذج ذات سعة سياق تبلغ مليون رمز مميّز معالجة فيديوهات تصل مدتها إلى ساعة واحدة بدقة الوسائط التلقائية أو 3 ساعات بدقة الوسائط المنخفضة.
  • معالجة File API: عند استخدام File API، يتم أخذ عيّنات من الفيديوهات بمعدّل لقطة واحدة في الثانية، وتتم معالجة الصوت بمعدّل 1 كيلوبت في الثانية (قناة واحدة). تتم إضافة الطوابع الزمنية كل ثانية.
    • هذه المعدّلات عرضة للتغيير في المستقبل لتحسين الاستدلال.
  • احتساب الرموز المميزة: يتم تقسيم كل ثانية من الفيديو إلى رموز مميزة على النحو التالي:
    • اللقطات الفردية (يتم أخذ عينات بمعدّل لقطة واحدة في الثانية):
      • إذا تم ضبط mediaResolution على قيمة منخفضة، يتم تقسيم اللقطات إلى رموز مميزة بمعدل 66 رمزًا مميزًا لكل لقطة.
      • بخلاف ذلك، يتم تقسيم اللقطات إلى رموز مميزة بمعدل 258 رمزًا مميزًا لكل لقطة.
    • الصوت: 32 رمزًا مميزًا في الثانية
    • يتم تضمين البيانات الوصفية أيضًا.
    • الإجمالي: حوالي 300 رمز مميز لكل ثانية من الفيديو بدقة الوسائط التلقائية، أو 100 رمز مميز لكل ثانية من الفيديو بدقة الوسائط المنخفضة
  • تنسيق الطابع الزمني: عند الإشارة إلى لحظات معيّنة في فيديو ضمن طلبك، استخدِم التنسيق MM:SS (مثلاً ‫01:15 لمدة دقيقة واحدة و15 ثانية).
  • أفضل الممارسات:
    • استخدِم فيديو واحدًا فقط لكل طلب للحصول على أفضل النتائج.
    • في حال الجمع بين نص وفيديو واحد، ضَع طلب النص بعد جزء الفيديو في مصفوفة contents.
    • يُرجى العِلم أنّ تسلسلات اللقطات السريعة قد تفقد بعض التفاصيل بسبب معدّل أخذ العيّنات البالغ لقطة واحدة في الثانية. ننصحك بإبطاء سرعة هذه المقاطع إذا لزم الأمر.

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

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

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