超大视频文件理解 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 视频理解,价格比官方更优惠,适合大量视频分析场景。