巨大ビデオファイル理解API完全ガイド：100MBから2GBの動画を処理する3つの方法

"""
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 の動画をサポートしており、「限定公開（Unlisted）」に設定することでプライバシーを保護できます。
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

APIYI（apiyi.com）プラットフォーム経由で呼び出す場合、すべての標準的な動画処理方法がサポートされています。

現在、Gemini API は「非公開（Private）」動画の分析をサポートしていませんが、以下の 2 つの設定には対応しています。

アドバイス: 動画にプライバシーが含まれる場合は、「限定公開」に設定するのが最適です。プライバシーを保護しつつ、API での分析が可能です。

Gemini は動画セグメントの指定に 2 つの方法を提供しています。

方法1: タイムスタンプによるクエリ

prompt = "動画の 05:30 から 08:45 までの内容を分析してください"

方法2: 動画クロップパラメータ (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% 節約できます。
2. 分析セグメントを指定する: 必要な部分だけを分析し、全編処理を避けます。
3. アップロード済みファイルを再利用する: Files API でアップロードした後、URI を保存しておくことで、重複アップロードを避けます。

APIYI（apiyi.com）を通じて Gemini の動画理解機能を呼び出すと、公式よりもお得な料金で利用でき、大量の動画分析シーンに適しています。