الدليل الكامل لواجهة برمجة تطبيقات فهم ملفات الفيديو الضخمة: 3 طرق لمعالجة فيديوهات من 100 ميجابايت إلى 2 جيجابايت

لقد كان فهم الذكاء الاصطناعي لملفات الفيديو الضخمة دائمًا نقطة ألم للمطورين — فشل التحميل بسبب حجم الملف الكبير، وتجاوز سعة الذاكرة عند ترميز base64، والحصول على خطأ 413 من واجهة البرمجة. الخبر السار هو أن جوجل قامت في يناير 2026 بتحسين قدرات معالجة الملفات في Gemini API بشكل كبير: تم رفع حد التحميل المضمن من 20 ميجابايت إلى 100 ميجابايت، ويدعم Files API ما يصل إلى 2 جيجابايت، بالإضافة إلى ميزة تحليل روابط YouTube المباشرة الجديدة. سيتناول هذا المقال بالتفصيل 3 حلول لمعالجة الفيديوهات الضخمة لمساعدتك في اختيار المسار التقني الأنسب.

القيمة الجوهرية: بعد قراءة هذا المقال، ستتقن الحلول الكاملة للتعامل مع فيديوهات ضخمة تتراوح بين 100 ميجابايت و2 جيجابايت، وستتمكن من اختيار أفضل طريقة رفع بناءً على حجم الفيديو، وتكرار الاستخدام، وسيناريو العمل.

نظرة سريعة على حلول رفع ملفات الفيديو الضخمة في Gemini

قبل الخوض في التفاصيل التقنية، لنتعرف على الطرق الثلاث التي يوفرها Gemini لرفع الفيديو:

🎯 نصيحة جوهرية: بالنسبة لملفات الفيديو التي تتجاوز 100 ميجابايت، يفضل التفكير في رفعها على YouTube وتحليلها عبر الرابط، أو استخدام Files API للرفع. كلتا الطريقتين قادرتان على معالجة ملفات الفيديو بحجم جيجابايت بشكل مستقر.

النماذج التي تدعم فهم الفيديو في Gemini

خيار فهم الفيديو في Gemini رقم 1: التحليل المباشر لروابط YouTube

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

المزايا الأساسية لخيار روابط YouTube

نموذج كود فهم الفيديو عبر رابط YouTube

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # استخدام واجهة APIYI الموحدة
)

# تحليل الفيديو عبر رابط YouTube
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "يرجى تحليل المحتوى الرئيسي لهذا الفيديو، وإدراج النقاط الزمنية الرئيسية والأحداث المقابلة"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ],
    max_tokens=4096
)

print(response.choices[0].message.content)

قيود استخدام خيار روابط YouTube

💡 نصيحة عملية: إذا كان محتوى الفيديو يتضمن خصوصية، يمكنك ضبط فيديو YouTube على وضع "غير مدرج" (Unlisted)، وبذلك لن يتمكن من الوصول إليه إلا من يملك الرابط، ومع ذلك ستظل واجهة برمجة تطبيقات Gemini قادرة على تحليله بشكل طبيعي. عند الاستدعاء عبر منصة APIYI (apiyi.com)، فإن ميزة روابط YouTube مدعومة أيضاً.

مثال على الاستعلام بنقاط زمنية

يدعم Gemini الاستعلام الدقيق عن نقاط زمنية محددة في الفيديو:

# الاستعلام عن محتوى نقاط زمنية محددة في الفيديو
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "يرجى إخباري بما يتم عرضه في النقطتين الزمنيتين 02:30 و 05:45 على التوالي؟"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ]
)

خيار فهم الفيديو في Gemini رقم 2: رفع الملفات الكبيرة عبر Files API

بالنسبة للفيديوهات الخاصة التي لا يمكن رفعها على YouTube (مثل التدريب الداخلي أو الأسرار التجارية)، فإن Files API هو الخيار الأفضل للتعامل مع فيديوهات تتراوح أحجامها بين 100 ميجابايت و 2 جيجابايت.

سير عمل Files API

ملف فيديو محلي ← رفع عبر Files API ← الحصول على file_uri ← إرسال طلب التحليل

نموذج كود كامل لاستخدام Files API

import google.generativeai as genai
import time

# تكوين واجهة برمجة التطبيقات (API)
genai.configure(api_key="YOUR_API_KEY")

def upload_large_video(video_path: str) -> str:
    """
    رفع فيديو كبير إلى Gemini Files API
    يدعم ملفات حتى 2 جيجابايت
    """
    print(f"جاري رفع الفيديو: {video_path}")

    # رفع الملف
    video_file = genai.upload_file(
        path=video_path,
        display_name="large_video"
    )

    # انتظار اكتمال معالجة الملف
    while video_file.state.name == "PROCESSING":
        print("قيد المعالجة...")
        time.sleep(5)
        video_file = genai.get_file(video_file.name)

    if video_file.state.name == "FAILED":
        raise ValueError(f"فشلت معالجة الملف: {video_file.state.name}")

    print(f"تم الرفع بنجاح! URI: {video_file.uri}")
    return video_file.uri

def analyze_video(file_uri: str, prompt: str) -> str:
    """
    تحليل الفيديو المرفوع مسبقاً
    """
    model = genai.GenerativeModel("gemini-3-pro-preview")

    response = model.generate_content([
        file_uri,
        prompt
    ])

    return response.text

# مثال على الاستخدام
video_uri = upload_large_video("/path/to/large_video.mp4")
result = analyze_video(
    video_uri,
    "يرجى تحليل محتوى هذا الفيديو بالتفصيل، بما في ذلك المشاهد الرئيسية، وأنشطة الأشخاص، والمعلومات الهامة"
)
print(result)

إدارة الملفات في Files API

# عرض قائمة بجميع الملفات المرفوعة
for file in genai.list_files():
    print(f"اسم الملف: {file.name}")
    print(f"  URI: {file.uri}")
    print(f"  الحجم: {file.size_bytes / 1024 / 1024:.2f} ميجابايت")
    print(f"  الحالة: {file.state.name}")
    print()

# حذف الملفات التي لم تعد هناك حاجة إليها (لتوفير مساحة التخزين)
genai.delete_file(file.name)

🎯 تحسين التكلفة: يمكن إعادة استخدام الملفات المرفوعة عبر Files API في طلبات متعددة، مما يتجنب تكرار الرفع. يُنصح برفع الفيديو مرة واحدة للفيديوهات التي تتطلب تحليلات متعددة، ثم حفظ الـ file_uri لاستخدامه لاحقاً. عند الاستدعاء عبر منصة APIYI (apiyi.com)، تتوفر أيضاً الوظائف الكاملة لـ Files API.

الخيار الثالث لفهم الفيديو في Gemini: الرفع المضمن بصيغة Base64

بالنسبة لمقاطع الفيديو الصغيرة التي يقل حجمها عن 100 ميجابايت، يعد التحميل المضمن (Inline) بصيغة Base64 الطريقة الأسهل، حيث يتطلب الأمر استدعاءً واحدًا فقط لـ API لإتمام العملية.

نموذج كود للتحميل المضمن بصيغة Base64

import openai
import base64
from pathlib import Path

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI الواجهة الموحدة
)

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    الرفع المضمن للفيديو لتحليله (مناسب للفيديوهات ≤ 100 ميجابايت)
    """
    # قراءة الفيديو وترميزه
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"حجم الفيديو {video_size_mb:.2f} ميجابايت يتجاوز الحد المسموح به (100 ميجابايت)، يرجى استخدام Files API")

    video_base64 = base64.b64encode(video_bytes).decode('utf-8')

    # تحديد نوع MIME
    suffix = Path(video_path).suffix.lower()
    mime_types = {
        '.mp4': 'video/mp4',
        '.avi': 'video/avi',
        '.mov': 'video/quicktime',
        '.webm': 'video/webm',
        '.mkv': 'video/x-matroska'
    }
    mime_type = mime_types.get(suffix, 'video/mp4')

    response = client.chat.completions.create(
        model="gemini-3-pro-preview",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "image_url",  # يتم استخدام نوع image_url للفيديو أيضاً
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# مثال على الاستخدام
result = analyze_video_inline(
    "short_clip.mp4",
    "يرجى وصف المحتوى الرئيسي لمقطع الفيديو هذا"
)
print(result)

ملاحظات هامة حول التحميل المضمن بصيغة Base64

حساب الـ Tokens وتحسين التكلفة في فهم الفيديو مع Gemini

يعد فهم قواعد حساب الـ Tokens أمرًا بالغ الأهمية للتحكم في التكاليف.

معادلة حساب الـ Tokens للفيديو في Gemini

استهلاك الـ Tokens لمقاطع الفيديو ذات الأطوال المختلفة

ضبط الدقة المنخفضة لتوفير التكاليف

# استخدم الدقة المنخفضة لمعالجة مقاطع الفيديو الطويلة لتوفير 67% من الـ Tokens
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # بدقة 360p، تستهلك 100 توكن/ثانية
    }
)

💰 تحسين التكلفة: بالنسبة لمهام فهم المحتوى (مثل ملخصات الفيديو أو تصنيف المحتوى)، عادةً ما تكون الدقة المنخفضة كافية. لا تحتاج إلى الدقة العالية إلا عند الحاجة للتعرف على التفاصيل الدقيقة (مثل النصوص أو الأشياء الصغيرة). من خلال استدعاء وظائف فهم الفيديو في Gemini عبر APIYI (apiyi.com)، يمكنك الحصول على أسعار أكثر تنافسية.

تطبيق عملي لمعالجة الفيديوهات الضخمة باستخدام Gemini: سير العمل الكامل

فيما يلي حل كامل يختار تلقائيًا أفضل طريقة رفع بناءً على حجم الفيديو.

"""
Gemini 超大视频文件理解完整解决方案
自动根据视频大小选择最佳上传方式
"""

import openai
import google.generativeai as genai
import base64
import time
from pathlib import Path
from typing import Optional, Union
from dataclasses import dataclass
from enum import Enum

class UploadMethod(Enum):
    INLINE = "inline"
    FILES_API = "files_api"
    YOUTUBE = "youtube"

@dataclass
class VideoAnalysisResult:
    success: bool
    method: UploadMethod
    content: Optional[str] = None
    error: Optional[str] = None
    tokens_used: Optional[int] = None

class GeminiVideoAnalyzer:
    """
    智能视频分析器
    自动选择最佳上传方式处理各种大小的视频
    """

    # 文件大小阈值 (字节)
    INLINE_MAX_SIZE = 100 * 1024 * 1024  # 100MB
    FILES_API_MAX_SIZE = 2 * 1024 * 1024 * 1024  # 2GB

    def __init__(
        self,
        api_key: str,
        base_url: str = "https://api.apiyi.com/v1"
    ):
        self.client = openai.OpenAI(
            api_key=api_key,
            base_url=base_url
        )
        genai.configure(api_key=api_key)

    def _get_file_size(self, video_path: str) -> int:
        """获取文件大小"""
        return Path(video_path).stat().st_size

    def _choose_method(
        self,
        video_path: Optional[str] = None,
        youtube_url: Optional[str] = None
    ) -> UploadMethod:
        """根据输入自动选择上传方式"""

        if youtube_url:
            return UploadMethod.YOUTUBE

        if video_path:
            file_size = self._get_file_size(video_path)
            if file_size <= self.INLINE_MAX_SIZE:
                return UploadMethod.INLINE
            elif file_size <= self.FILES_API_MAX_SIZE:
                return UploadMethod.FILES_API
            else:
                raise ValueError(
                    f"文件大小 {file_size / 1024 / 1024 / 1024:.2f}GB "
                    f"超过 2GB 限制,请上传到 YouTube 后使用 URL 分析"
                )

        raise ValueError("必须提供 video_path 或 youtube_url")

    def _analyze_inline(
        self,
        video_path: str,
        prompt: str,
        media_resolution: str = "standard"
    ) -> str:
        """内联上传分析"""
        video_bytes = Path(video_path).read_bytes()
        video_base64 = base64.b64encode(video_bytes).decode('utf-8')

        suffix = Path(video_path).suffix.lower()
        mime_types = {
            '.mp4': 'video/mp4',
            '.avi': 'video/avi',
            '.mov': 'video/quicktime',
            '.webm': 'video/webm'
        }
        mime_type = mime_types.get(suffix, 'video/mp4')

        response = self.client.chat.completions.create(
            model="gemini-3-pro-preview",
            messages=[{
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }],
            extra_body={"media_resolution": media_resolution}
        )

        return response.choices[0].message.content

    def _analyze_files_api(
        self,
        video_path: str,
        prompt: str,
        media_resolution: str = "standard"
    ) -> str:
        """Files API 上传分析"""
        # 上传文件
        video_file = genai.upload_file(path=video_path)

        # 等待处理完成
        while video_file.state.name == "PROCESSING":
            time.sleep(5)
            video_file = genai.get_file(video_file.name)

        if video_file.state.name == "FAILED":
            raise ValueError("文件处理失败")

        # 分析视频
        model = genai.GenerativeModel("gemini-3-pro-preview")
        response = model.generate_content(
            [video_file, prompt],
            generation_config={
                "media_resolution": media_resolution
            }
        )

        return response.text

    def _analyze_youtube(
        self,
        youtube_url: str,
        prompt: str,
        media_resolution: str = "standard"
    ) -> str:
        """YouTube URL 分析"""
        response = self.client.chat.completions.create(
            model="gemini-3-pro-preview",
            messages=[{
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "video_url",
                        "video_url": {"url": youtube_url}
                    }
                ]
            }],
            extra_body={"media_resolution": media_resolution}
        )

        return response.choices[0].message.content

    def analyze(
        self,
        prompt: str,
        video_path: Optional[str] = None,
        youtube_url: Optional[str] = None,
        media_resolution: str = "standard",
        force_method: Optional[UploadMethod] = None
    ) -> VideoAnalysisResult:
        """
        分析视频内容

        Args:
            prompt: 分析提示词
            video_path: 本地视频路径 (可选)
            youtube_url: YouTube 视频 URL (可选)
            media_resolution: 分辨率 ("low"/"standard"/"high")
            force_method: 强制使用的上传方式 (可选)

        Returns:
            VideoAnalysisResult 对象
        """

        try:
            # 选择上传方式
            method = force_method or self._choose_method(video_path, youtube_url)
            print(f"使用上传方式: {method.value}")

            # 执行分析
            if method == UploadMethod.INLINE:
                content = self._analyze_inline(video_path, prompt, media_resolution)
            elif method == UploadMethod.FILES_API:
                content = self._analyze_files_api(video_path, prompt, media_resolution)
            elif method == UploadMethod.YOUTUBE:
                content = self._analyze_youtube(youtube_url, prompt, media_resolution)

            return VideoAnalysisResult(
                success=True,
                method=method,
                content=content
            )

        except Exception as e:
            return VideoAnalysisResult(
                success=False,
                method=method if 'method' in dir() else UploadMethod.INLINE,
                error=str(e)
            )


# 使用示例
if __name__ == "__main__":
    analyzer = GeminiVideoAnalyzer(api_key="your-api-key")

    # 示例1: 小视频 (自动使用内联上传)
    result = analyzer.analyze(
        prompt="请描述视频内容",
        video_path="small_clip.mp4"
    )

    # 示例2: 大视频 (自动使用 Files API)
    result = analyzer.analyze(
        prompt="请分析这个培训视频的主要知识点",
        video_path="training_video_500mb.mp4",
        media_resolution="low"  # 长视频用低分辨率节省成本
    )

    # 示例3: YouTube 视频
    result = analyzer.analyze(
        prompt="请总结这个视频的核心观点",
        youtube_url="https://www.youtube.com/watch?v=VIDEO_ID"
    )

    if result.success:
        print(f"分析方式: {result.method.value}")
        print(f"结果:\n{result.content}")
    else:
        print(f"分析失败: {result.error}")

الأسئلة الشائعة حول فهم الفيديو باستخدام Gemini

# ضغط الفيديو باستخدام FFmpeg ليكون أقل من 1 جيجابايت
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# تقسيم الفيديو إلى مقاطع مدتها 10 دقائق
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "يرجى تحليل محتوى الفيديو بين الدقيقة 05:30 و 08:45"

response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "video_clip": {
            "start_time": "00:05:30",
            "end_time": "00:08:45"
        }
    }
)

ملخص حلول معالجة الفيديوهات الضخمة في Gemini

يقدم هذا المقال ثلاثة حلول متكاملة للتعامل مع ملفات الفيديو الضخمة:

مسار اتخاذ القرار لاختيار الحل

هل الفيديو موجود بالفعل على YouTube؟
├── نعم ← استخدم رابط YouTube (الأبسط)
└── لا ← ما هو حجم الفيديو؟
    ├── ≤ 100 ميجابايت ← Base64 ضمني (طلب واحد)
    ├── 100 ميجابايت - 2 جيجابايت ← Files API (يدعم إعادة الاستخدام)
    └── > 2 جيجابايت ← ارفعه على YouTube أو قم بضغطه/تقسيمه

🎯 النصيحة النهائية: بالنسبة لملفات الفيديو الضخمة، أعطِ الأولوية لحل رابط YouTube؛ فهو لا يتخلص من قيود حجم الملف فحسب، بل يستفيد أيضاً من تكامل Google الأصلي لتحقيق أقل زمن انتقال. نوصي باستخدام ميزات فهم الفيديو في Gemini عبر APIYI (apiyi.com) للحصول على أسعار أفضل وخدمة مستقرة.

تمت كتابة هذا المقال بواسطة الفريق التقني في APIYI. لمزيد من النصائح حول استخدام واجهات برمجة تطبيقات الذكاء الاصطناعي متعدد الوسائط، تفضل بزيارة apiyi.com للحصول على الدعم التقني.