초대형 동영상 파일 이해 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의 비디오를 지원하며, '일부 공개'로 설정하면 개인정보를 보호할 수 있습니다.
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) 비디오 분석은 지원하지 않지만, 다음 두 가지는 지원합니다.

팁: 비디오에 민감한 내용이 포함되어 있다면 '일부 공개'로 설정하는 것이 가장 좋습니다. 개인정보를 보호하면서 API 분석도 가능하기 때문입니다.

Gemini는 비디오 구간을 지정하는 두 가지 방식을 지원합니다.

방법 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 비디오 이해 기능을 호출하면 공식 가격보다 더 저렴하게 이용할 수 있어 대량의 비디오 분석 시나리오에 적합합니다.