Panduan Lengkap API Pemahaman File Video Ekstra Besar: 3 Metode Menangani Video 100MB hingga 2GB

Memproses pemahaman AI untuk file video yang sangat besar selalu menjadi masalah bagi pengembang—file terlalu besar sehingga unggahan timeout, enkripsi base64 menyebabkan memory overflow, atau antarmuka mengembalikan kesalahan 413. Kabar baiknya adalah, pada Januari 2026, Google secara signifikan meningkatkan kemampuan pemrosesan file Gemini API: batas unggahan inline ditingkatkan dari 20MB menjadi 100MB, Files API kini mendukung hingga 2GB, dan fitur baru analisis langsung via URL YouTube telah ditambahkan. Artikel ini akan menjelaskan secara rinci 3 solusi untuk menangani video sangat besar guna membantu Anda memilih jalur teknis yang paling sesuai.

Nilai Inti: Setelah membaca artikel ini, Anda akan menguasai solusi lengkap untuk memproses video besar dari 100MB hingga 2GB, serta mampu memilih metode unggah terbaik berdasarkan ukuran video, frekuensi penggunaan, dan skenario bisnis.

Kilasan Solusi Unggah File Video Sangat Besar di Gemini

Sebelum masuk ke detail teknis, mari kita pahami tiga cara unggah video yang disediakan oleh Gemini:

🎯 Saran Inti: Untuk file video yang melebihi 100MB, prioritaskan mengunggah ke YouTube untuk dianalisis melalui URL, atau gunakan Files API. Kedua metode ini dapat memproses file video tingkat GB dengan stabil.

Model yang Mendukung Pemahaman Video Gemini

Gemini Video Understanding Solusi 1: Analisis Langsung URL YouTube

Untuk file video yang sangat besar, solusi yang paling elegan adalah mengunggahnya ke YouTube, lalu membiarkan Gemini menganalisisnya langsung melalui URL. Ini adalah integrasi native dari Google, tanpa memerlukan transfer file manual.

Keunggulan Inti Solusi URL YouTube

Contoh Kode Analisis Video URL YouTube

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Menggunakan antarmuka terpadu APIYI
)

# Menganalisis video melalui URL YouTube
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Tolong analisis konten utama video ini, buat daftar titik waktu penting dan peristiwa yang sesuai"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ],
    max_tokens=4096
)

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

Batasan Penggunaan Solusi URL YouTube

💡 Tip Praktis: Jika konten video bersifat sensitif, Anda dapat menyetel video YouTube ke status "Unlisted". Dengan begitu, hanya orang yang mengetahui tautannya yang dapat mengaksesnya, namun Gemini API tetap dapat menganalisisnya secara normal. Saat memanggil melalui APIYI apiyi.com, fitur URL YouTube ini juga didukung sepenuhnya.

Contoh Kueri Stempel Waktu (Timestamp)

Gemini mendukung kueri yang tepat untuk titik waktu tertentu dalam video:

# Menanyakan konten pada titik waktu tertentu dalam video
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Tolong beri tahu saya konten apa yang ditampilkan pada titik waktu 02:30 dan 05:45?"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ]
)

Gemini Video Understanding Solusi 2: Unggah File Besar dengan Files API

Untuk video pribadi yang tidak dapat diunggah ke YouTube (seperti pelatihan internal atau rahasia dagang), Files API adalah pilihan terbaik untuk menangani video berukuran 100MB hingga 2GB.

Alur Unggahan Files API

File video lokal → Unggah via Files API → Dapatkan file_uri → Kirim permintaan analisis

Contoh Kode Lengkap Files API

import google.generativeai as genai
import time

# Konfigurasi API
genai.configure(api_key="YOUR_API_KEY")

def upload_large_video(video_path: str) -> str:
    """
    Mengunggah file video besar ke Gemini Files API
    Mendukung file hingga maksimal 2GB
    """
    print(f"Sedang mengunggah video: {video_path}")

    # Unggah file
    video_file = genai.upload_file(
        path=video_path,
        display_name="large_video"
    )

    # Menunggu pemrosesan file selesai
    while video_file.state.name == "PROCESSING":
        print("Sedang memproses...")
        time.sleep(5)
        video_file = genai.get_file(video_file.name)

    if video_file.state.name == "FAILED":
        raise ValueError(f"Pemrosesan file gagal: {video_file.state.name}")

    print(f"Unggahan berhasil! URI: {video_file.uri}")
    return video_file.uri

def analyze_video(file_uri: str, prompt: str) -> str:
    """
    Menganalisis video yang telah diunggah
    """
    model = genai.GenerativeModel("gemini-3-pro-preview")

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

    return response.text

# Contoh penggunaan
video_uri = upload_large_video("/path/to/large_video.mp4")
result = analyze_video(
    video_uri,
    "Tolong analisis konten video ini secara detail, termasuk adegan utama, aktivitas karakter, dan informasi penting"
)
print(result)

Manajemen File Files API

# Mencantumkan semua file yang telah diunggah
for file in genai.list_files():
    print(f"Nama File: {file.name}")
    print(f"  URI: {file.uri}")
    print(f"  Ukuran: {file.size_bytes / 1024 / 1024:.2f} MB")
    print(f"  Status: {file.state.name}")
    print()

# Menghapus file yang tidak lagi dibutuhkan (menghemat ruang penyimpanan)
genai.delete_file(file.name)

🎯 Optimasi Biaya: File yang diunggah melalui Files API dapat digunakan kembali dalam beberapa permintaan, menghindari pengunggahan berulang. Disarankan untuk video yang perlu dianalisis berkali-kali, unggah sekali saja, lalu simpan file_uri untuk penggunaan selanjutnya. Saat memanggil melalui platform APIYI apiyi.com, fungsionalitas penuh Files API juga didukung.

Solusi Pemahaman Video Gemini 3: Unggah Inline Base64

Untuk video kecil di bawah 100MB, unggah inline Base64 adalah cara yang paling simpel karena hanya butuh satu kali panggilan API saja.

Contoh Kode Unggah Inline Base64

import openai
import base64
from pathlib import Path

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Antarmuka terpadu APIYI
)

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    Unggah video secara inline untuk analisis (cocok untuk video ≤100MB)
    """
    # Membaca dan melakukan encoding video
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"Ukuran video {video_size_mb:.2f}MB melebihi batas 100MB, silakan gunakan Files API")

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

    # Menentukan tipe 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",  # Video juga menggunakan tipe image_url
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# Contoh penggunaan
result = analyze_video_inline(
    "short_clip.mp4",
    "Tolong deskripsikan konten utama dari cuplikan video ini"
)
print(result)

Hal yang Perlu Diperhatikan pada Unggah Inline Base64

Perhitungan Token dan Optimasi Biaya Pemahaman Video Gemini

Memahami aturan perhitungan Token sangat krusial untuk mengendalikan biaya.

Rumus Perhitungan Token Video Gemini

Konsumsi Token untuk Berbagai Durasi Video

Mengatur Resolusi Rendah untuk Hemat Biaya

# Gunakan resolusi rendah untuk memproses video durasi panjang, hemat 67% token
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # 360p, 100 token/detik
    }
)

💰 Optimasi Biaya: Untuk tugas pemahaman konten (seperti ringkasan video, klasifikasi konten), menggunakan resolusi rendah biasanya sudah cukup. Resolusi tinggi hanya diperlukan jika Anda butuh mengenali detail spesifik (seperti teks atau objek kecil). Dengan menggunakan fitur pemahaman video Gemini melalui APIYI apiyi.com, Anda bisa mendapatkan harga yang lebih kompetitif.

Praktik Pemrosesan Video Super Besar Gemini: Alur Kerja Lengkap

Berikut adalah solusi lengkap untuk memilih metode unggah terbaik secara otomatis berdasarkan ukuran video.

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

Pertanyaan Umum Seputar Pemahaman Video Gemini

# Mengompres video hingga di bawah 1GB menggunakan FFmpeg
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# Memotong video menjadi bagian-bagian berdurasi 10 menit
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "Tolong analisis konten video antara menit 05:30 sampai 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"
        }
    }
)

Artikel ini membahas 3 solusi lengkap untuk menangani file video berukuran sangat besar:

Alur Keputusan Pemilihan Solusi

Apakah video sudah ada di YouTube?
├── Ya → Gunakan YouTube URL (paling simpel)
└── Tidak → Berapa ukuran videonya?
    ├── ≤ 100MB → Inline Base64 (permintaan tunggal)
    ├── 100MB-2GB → Files API (mendukung penggunaan ulang)
    └── > 2GB → Unggah ke YouTube atau kompres/bagi file

🎯 Saran Akhir: Untuk file video super besar, prioritaskan solusi YouTube URL. Selain tidak ada batasan ukuran file, cara ini memanfaatkan integrasi native Google untuk latensi terendah. Direkomendasikan untuk memanggil fitur pemahaman video Gemini melalui APIYI apiyi.com guna mendapatkan harga yang lebih kompetitif dan layanan yang stabil.

Artikel ini ditulis oleh tim teknis APIYI. Untuk informasi lebih lanjut mengenai tips penggunaan API AI multimodal, silakan kunjungi apiyi.com untuk bantuan teknis.