超大視頻文件理解 API 完全指南: 3 種方法處理 100MB 到 2GB 視頻

"""
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}"）

超過 2GB 的視頻有以下解決方案:

1. 上傳到 YouTube: 最推薦的方式，YouTube 支持最大 256GB 的視頻，設爲"不公開"即可保護隱私
2. 視頻壓縮: 使用 FFmpeg 降低分辨率或碼率
3. 視頻分割: 將長視頻分割成多個片段分別分析

# FFmpeg 壓縮視頻到 1GB 以內
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

通過 API易 apiyi.com 平臺調用時，支持所有標準的視頻處理方式。

目前 Gemini API 不支持分析私有 （Private） 視頻，但支持以下兩種:

建議: 如果視頻涉及隱私，設爲"不公開"是最佳選擇，既能保護隱私又能使用 API 分析。

Gemini 支持兩種方式指定視頻片段:

方式一: 時間戳查詢

prompt = "請分析視頻 05:30 到 08:45 之間的內容"

方式二: 視頻裁剪參數 （2026 新功能）

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"
        }
    }
）

長視頻成本優化的 3 個技巧:

1. 使用低分辨率: 設置 media_resolution: "low" 可節省 67% token
2. 指定分析片段: 只分析需要的部分，避免全量處理
3. 複用已上傳文件: 通過 Files API 上傳後保存 URI，避免重複上傳

通過 API易 apiyi.com 調用 Gemini 視頻理解，價格比官方更優惠，適合大量視頻分析場景。