فهم الفيديو

لمزيد من المعلومات حول إنشاء الفيديوهات، يُرجى الاطّلاع على دليل 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
import time

client = genai.Client()

myfile = client.files.upload(file="path/to/sample.mp4")

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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.output_text)

JavaScript

import { GoogleGenAI } 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" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

جافا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

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

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

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

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

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

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

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

Python

from google import genai
import base64

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.8-flash',
    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.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

جافا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

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

يمكنك تمرير عناوين URL على YouTube مباشرةً إلى Gemini API كجزء من طلبك على النحو التالي:

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  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.output_text);

جافا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

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

القيود:

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

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

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

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

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

اختَر وضع المعالجة الذي يتطابق مع مدة الفيديو ونوع طلب البحث:

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

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

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

لاستخدام ميزة "فهم الفيديو المستند إلى الذكاء الاصطناعي الوكيل"، يجب ضبط "processing": "agentic" على جزء الفيديو في مصفوفة input.

قد تستغرق معالجة الفيديوهات الطويلة وقتًا أطول لأنّ النموذج يجري عمليات فحص متعددة للتنقّل في المخطط الزمني. لتجنُّب فقدان التقدّم في حال انقطاع الاتصال بالشبكة، يستخدم هذا المثال background=True لتنفيذ المهمة بشكل غير متزامن على الخادم. يمكنك أيضًا تنفيذ الطلبات بشكل متزامن بدون تنفيذها في الخلفية من خلال حذف المَعلمة background، وهو أمر مناسب للفيديوهات القصيرة.

للحصول على تفاصيل حول الاستطلاع واسترداد النتائج وإدارة المهام في الخلفية، يُرجى الاطّلاع على دليل التنفيذ في الخلفية.

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
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)

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

// Upload a long video
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 });
}

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

ملاحظة: للتأكّد من استخدام المعالجة المستندة إلى الوكلاء، افحص interaction.steps. يشير ظهور processing_call وprocessing_result إلى أنّ النموذج تنقّل في الفيديو بشكل ديناميكي.

خطوات الردّ

تضيف المعالجة المستندة إلى الوكيل نوعَين جديدَين من الخطوات إلى مصفوفة steps:

  • ‫processing_call: طلب النموذج مقطع فيديو أو نصًا صوتيًا، يتم تحديدهما من خلال id.
  • ‫processing_result: نتيجة هذا التحميل، مرتبطة بـ call_id.

تظهر هذه الخطوات بالتناوب مع خطوات thought (عند تفعيل الملخّصات) وتسبق خطوة model_output النهائية. ويمكن استخدامها لعرض تتبُّع مستوى التقدّم في واجهة المستخدم، ولكنّها لا تتطلّب ردًا.

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

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

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

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

Python

import time
from google import genai

client = genai.Client()

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

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_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" }
});

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

محادثات فيديو مترابطة

يتم الحفاظ على سياق الفيديو في جميع مراحل المحادثة. عند استخدام المعالجة المستندة إلى الوكلاء:

  • الوضع مع حفظ الحالة (باستخدام previous_interaction_id): يحتفظ الخادم بسياق الفيديو. ليس عليك اتّخاذ أي إجراء إضافي.
  • وضع عدم حفظ السياق (باستخدام step_list): في وضع عدم حفظ السياق، يتضمّن الردّ الخطوتَين processing_call وprocessing_result اللتَين تشفّران سياق الفيديو. يجب تضمين جميع الخطوات من الرد في طلبك التالي step_list للحفاظ على سياق الفيديو. ومع أنّ حذفها لا يؤدي حاليًا إلى ظهور خطأ في واجهة برمجة التطبيقات، إلا أنّه يؤدي إلى فقدان سياق الفيديو، ما يقلّل بشكل كبير من جودة الردود على الأسئلة اللاحقة. يُرجى العِلم أنّ الخطوات التي يتم عرضها في الطلبات اللاحقة تساهم في عدد الرموز المميزة للإدخال.

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

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

Python

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

JavaScript

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

جافا

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

Go

prompt := "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 = "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.";

جافا

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

Go

prompt := "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".

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

يمكنك قص الفيديو من خلال تحديد start_offset وend_offset في عنصر الإعداد processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

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

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

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

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

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

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

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

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

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

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

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

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