فهم الفيديو

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

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

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

قبل البدء

قبل استدعاء واجهة برمجة التطبيقات Gemini API، تأكَّد من تثبيت حزمة تطوير البرامج (SDK) المفضّلة لديك ، وضبط مفتاح واجهة برمجة التطبيقات Gemini API وجاهزيته للاستخدام.

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

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

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

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

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

تقبل واجهة برمجة التطبيقات File API تنسيقات ملفات الفيديو مباشرةً. يستخدِم هذا المثال القصير فيلم وكالة ناسا "تقلص البقعة الحمراء الكبيرة على كوكب المشتري ونموها". مصدر الصورة: مركز Goddard لرحلات الفضاء (GSFC)/ديفيد لاد (2018).

إنّ الفيديو "تقلّص ونمو البقعة الحمراء الكبيرة على كوكب المشتري" متاح للجميع ولا يعرض أشخاصًا يمكن التعرّف عليهم. (إرشادات استخدام صور ووسائط وكالة ناسا)

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

Python

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)

JavaScript

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)

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?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 ميغابايت.

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

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

JavaScript

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

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

تضمين عنوان URL لفيديو على YouTube

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

القيود:

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

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

Python

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

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

انتقال

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

REST

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.

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

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

REST

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

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

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

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