لمزيد من المعلومات حول إنشاء الفيديوهات، اطّلِع على دليل 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 3.8 Flash و3.6 Flash و3.5 Flash Lite أيضًا ميزة الفهم التفاعلي للفيديوهات، حيث يستكشف النموذج المخطط الزمني للفيديو بشكل ديناميكي، ويتفحّص النصوص بشكل انتقائي، ويعدّل عدد اللقطات في الثانية ودرجة الدقة بشكل تكيفي أثناء التنقل استنادًا إلى الطلب.
| الوضع | الوصف | الطُرز المتوافقة |
|---|---|---|
| ثابتة (تلقائي) | يستخرج اللقطات بمعدّل ثابت (لقطة واحدة في الثانية) ويضعها في السياق في عملية واحدة. تعمل هذه الميزة بشكل جيد مع المقاطع القصيرة. | جميع نماذج Gemini |
| Agentic | يتنقّل النموذج ديناميكيًا في المخطط الزمني للفيديو، ولا يحمّل سوى المحتوى الذي يحتاجه استنادًا إلى الطلب. زيادة في كفاءة استخدام الرموز المميزة بنسبة تصل إلى% 88 وتحسين الجودة بنسبة% 7 تقريبًا في المحتوى الطويل | Gemini 3.8 Flash و3.6 Flash و3.5 Flash Lite |
اختيار وضع المعالجة
كقاعدة عامة، ننصحك بالبدء باستخدام الوضع الذي يتضمّن وكيلًا، خاصةً عند تحسين جودة الردود أو كفاءة الرموز المميزة.
- الاستهداف المباشر: فيديوهات طويلة أو طلبات بحث تستهدف لحظات معيّنة يتنقّل النموذج بشكل ديناميكي في المخطط الزمني لاستهداف المعلومات ذات الصلة بالسياق بدون ملء قدرة الاستيعاب.
- ثابتة: طلبات البحث التي تتطلّب استجابة سريعة على مقاطع قصيرة (أقل من 5 دقائق)، أو الحالات التي تتطلّب دقة على مستوى الإطار في المقطع بأكمله
ملاحظة: بالنسبة إلى الفيديوهات الطويلة أو الطلبات المعقّدة التي تستغرق معالجتها وقتًا أطول، استخدِم البث (
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/mp4video/mpegvideo/movvideo/avivideo/x-flvvideo/mpgvideo/webmvideo/wmvvideo/3gpp
التفاصيل الفنية حول الفيديوهات
- النماذج المتوافقة والسياق: يمكن لجميع نماذج Gemini معالجة بيانات الفيديو.
- يمكن للنماذج التي تتضمّن قدرة استيعاب مليون رمز مميّز معالجة فيديوهات تصل مدتها إلى 3 ساعات تلقائيًا (بدرجة دقة منخفضة للوسائط)، أو فيديوهات تصل مدتها إلى ساعة واحدة بدرجة دقة عالية للوسائط.
- طرق المعالجة: تتوافق نماذج Gemini 3.8 Flash و3.6 Flash و3.5 Flash Lite والنماذج الأحدث مع طريقتَين لمعالجة الفيديو:
- ثابتة: يتم استخراج اللقطات بمعدّل لقطة واحدة في الثانية ووضعها في السياق (الإعداد التلقائي لجميع النماذج). تتم معالجة الصوت بمعدل 1 كيلوبت في الثانية (قناة واحدة). تتم إضافة الطوابع الزمنية كل ثانية. هذا الخيار هو الأفضل للمقاطع القصيرة أو عندما يكون كل إطار مهمًا (مثل الفحص إطارًا بإطار). يُرجى العِلم أنّ تسلسلات اللقطات السريعة قد تفقد بعض التفاصيل بسبب معدّل أخذ العيّنات البالغ لقطة واحدة في الثانية.
- التفاعلية: يتنقّل النموذج ديناميكيًا في الفيديو، ويحمّل النص و/أو الإطارات و/أو الصوت عند الطلب. يستخدم هذا النموذج عددًا أقل من الرموز المميزة بنسبة تصل إلى %88 للمحتوى الطويل، مع أنّ التنقّل قد يؤدي إلى زيادة طفيفة في الوقت اللازم لظهور أول رمز مميز (TTFT) في المقاطع القصيرة (أقل من 5 دقائق) بسبب عمليات الاستدلال الداخلية والرحلات المتكررة للأدوات قبل بدء عملية الإنشاء. الأفضل للفيديوهات الطويلة لتحسين تكاليف الرموز المميزة وجودة الردود. متوافق مع Gemini 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 إنشاء الطلبات باستخدام بيانات نصية وصور وملفات صوتية وفيديوهات، ويُعرف ذلك أيضًا باسم إنشاء الطلبات المتعددة الوسائط.
- إرشادات الأمان: في بعض الأحيان، تُنشئ نماذج الذكاء الاصطناعي التوليدي نتائج غير متوقعة، مثل نتائج غير دقيقة أو متحيزة أو مسيئة. تُعدّ المعالجة اللاحقة والتقييم البشري أساسيَّين للحدّ من خطر الأضرار الناجمة عن هذه النتائج.