Vollständiger Leitfaden zur API für das Verständnis riesiger Videodateien: 3 Methoden zur Verarbeitung von 100 MB bis 2 GB Videos

Die KI-gestützte Analyse von sehr großen Videodateien war für Entwickler schon immer eine Herausforderung – Timeouts beim Hochladen, Speicherüberlauf bei der Base64-Kodierung oder 413-Fehlermeldungen der API. Die gute Nachricht: Im Januar 2026 hat Google die Dateiverarbeitungskapazitäten der Gemini API massiv erweitert: Das Limit für Inline-Uploads wurde von 20 MB auf 100 MB angehoben, die Files API unterstützt jetzt bis zu 2 GB, und es wurde eine Funktion zur direkten Analyse von YouTube-URLs hinzugefügt. In diesem Artikel werden wir diese drei Lösungen für den Umgang mit riesigen Videos im Detail erläutern, damit Sie den für Ihre Anforderungen am besten geeigneten technischen Weg wählen können.

Kerninhalt: Nach der Lektüre dieses Artikels werden Sie die vollständigen Lösungen für die Verarbeitung von Videodateien zwischen 100 MB und 2 GB beherrschen und in der Lage sein, die optimale Upload-Methode basierend auf Dateigröße, Nutzungshäufigkeit und Geschäftsszenario auszuwählen.

Schneller Überblick über die Gemini Video-Upload-Lösungen

Bevor wir in die technischen Details eintauchen, hier ein Überblick über die drei von Gemini angebotenen Video-Upload-Methoden:

🎯 Kernempfehlung: Für Videodateien über 100 MB sollten Sie vorrangig den Upload auf YouTube (Analyse via URL) oder die Verwendung der Files API in Betracht ziehen. Beide Methoden ermöglichen eine stabile Verarbeitung von Videos im Gigabyte-Bereich.

Von Gemini zur Videoanalyse unterstützte Modelle

Gemini Video-Verständnis Lösung 1: Direkte Analyse via YouTube-URL

Für sehr große Videodateien ist die eleganteste Lösung das Hochladen auf YouTube, um sie dann direkt von Gemini über die URL analysieren zu lassen. Dies ist eine native Integration von Google, die keinen Dateitransfer erfordert.

Kernvorteile der YouTube-URL-Lösung

Code-Beispiel für Video-Verständnis via YouTube-URL

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 APIYI 统一接口
)

# 通过 YouTube URL 分析视频
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "请分析这个视频的主要内容,列出关键时间点和对应的事件"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ],
    max_tokens=4096
)

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

Nutzungseinschränkungen der YouTube-URL-Lösung

💡 Praktischer Tipp: Wenn der Videoinhalt privat bleiben soll, können Sie das YouTube-Video auf "Nicht gelistet" (Unlisted) stellen. So haben nur Personen mit dem Link Zugriff, aber die Gemini API kann es dennoch normal analysieren. Diese YouTube-URL-Funktion wird auch bei Aufrufen über die APIYI-Plattform (apiyi.com) unterstützt.

Beispiel für Zeitstempel-Abfragen

Gemini unterstützt präzise Abfragen zu bestimmten Zeitpunkten im Video:

# 查询视频特定时间点的内容
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "请告诉我视频 02:30 和 05:45 这两个时间点分别在展示什么内容?"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ]
)

Gemini Video-Verständnis Lösung 2: Große Dateien über die Files API hochladen

Für private Videos, die nicht auf YouTube hochgeladen werden können (z. B. interne Schulungen, Geschäftsgeheimnisse), ist die Files API die beste Wahl für die Verarbeitung von Videos zwischen 100 MB und 2 GB.

Files API Upload-Prozess

Lokale Videodatei → Files API Upload → file_uri erhalten → Analyseanfrage stellen

Vollständiges Code-Beispiel für die Files API

import google.generativeai as genai
import time

# 配置 API
genai.configure(api_key="YOUR_API_KEY")

def upload_large_video(video_path: str) -> str:
    """
    上传大视频文件到 Gemini Files API
    支持最大 2GB 文件
    """
    print(f"正在上传视频: {video_path}")

    # 上传文件
    video_file = genai.upload_file(
        path=video_path,
        display_name="large_video"
    )

    # 等待文件处理完成
    while video_file.state.name == "PROCESSING":
        print("处理中...")
        time.sleep(5)
        video_file = genai.get_file(video_file.name)

    if video_file.state.name == "FAILED":
        raise ValueError(f"文件处理失败: {video_file.state.name}")

    print(f"上传成功! URI: {video_file.uri}")
    return video_file.uri

def analyze_video(file_uri: str, prompt: str) -> str:
    """
    分析已上传的视频
    """
    model = genai.GenerativeModel("gemini-3-pro-preview")

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

    return response.text

# 使用示例
video_uri = upload_large_video("/path/to/large_video.mp4")
result = analyze_video(
    video_uri,
    "请详细分析这个视频的内容,包括主要场景、人物活动和关键信息"
)
print(result)

Dateiverwaltung mit der Files API

# 列出所有已上传的文件
for file in genai.list_files():
    print(f"文件名: {file.name}")
    print(f"  URI: {file.uri}")
    print(f"  大小: {file.size_bytes / 1024 / 1024:.2f} MB")
    print(f"  状态: {file.state.name}")
    print()

# 删除不再需要的文件 (节省存储空间)
genai.delete_file(file.name)

🎯 Kostenoptimierung: Über die Files API hochgeladene Dateien können in mehreren Anfragen wiederverwendet werden, was doppelte Uploads vermeidet. Bei Videos, die mehrfach analysiert werden müssen, empfiehlt es sich, diese einmal hochzuladen und die file_uri für spätere Zwecke zu speichern. Die Files API wird mit ihrem vollen Funktionsumfang auch über die APIYI-Plattform (apiyi.com) unterstützt.

Gemini-Videoverständnis-Option 3: Inline-Upload via Base64

Für kleine Videos unter 100 MB ist der Inline-Upload via Base64 der einfachste Weg, da alles in einem einzigen API-Aufruf erledigt werden kann.

Codebeispiel für den Base64-Inline-Upload

import openai
import base64
from pathlib import Path

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

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    Video-Analyse via Inline-Upload (geeignet für Videos ≤ 100 MB)
    """
    # Video lesen und kodieren
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"Videogröße {video_size_mb:.2f} MB überschreitet das 100-MB-Limit. Bitte nutzen Sie die Files-API.")

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

    # MIME-Typ bestimmen
    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",  # Videos nutzen ebenfalls den Typ image_url
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# Anwendungsbeispiel
result = analyze_video_inline(
    "short_clip.mp4",
    "Bitte beschreibe den Hauptinhalt dieses Videoclips."
)
print(result)

Hinweise zum Base64-Inline-Upload

Gemini-Videoverständnis: Token-Berechnung und Kostenoptimierung

Das Verständnis der Token-Berechnungsregeln ist entscheidend für die Kostenkontrolle.

Gemini Video-Token-Berechnungsformel

Token-Verbrauch für verschiedene Videolängen

Kosten sparen durch niedrige Auflösung

# Niedrige Auflösung für lange Videos verwenden, spart 67 % der Tokens
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # 360p, 100 Tokens/Sekunde
    }
)

💰 Kostenoptimierung: Für Aufgaben zum Inhaltsverständnis (wie Video-Zusammenfassungen oder Inhaltsklassifizierung) reicht eine niedrige Auflösung meist aus. Nur wenn feine Details (wie Text oder kleine Objekte) erkannt werden müssen, ist eine hohe Auflösung erforderlich. Durch den Aufruf der Gemini-Videoverständnis-Funktion über APIYI (apiyi.com) können Sie zudem von attraktiveren Preisen profitieren.

Gemini Praxis für große Videoverarbeitung: Vollständiger Workflow

Hier ist eine vollständige Lösung zur automatischen Auswahl der besten Upload-Methode basierend auf der Videogröße.

"""
Vollständige Lösung für Gemini zur Verarbeitung extragroßer Videodateien
Wählt automatisch die beste Upload-Methode basierend auf der Videogröße
"""

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:
    """
    Intelligenter Video-Analyzer
    Wählt automatisch die beste Upload-Methode für Videos unterschiedlicher Größe
    """

    # Dateigrößen-Schwellenwert (Bytes)
    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:
        """Dateigröße abrufen"""
        return Path(video_path).stat().st_size

    def _choose_method(
        self,
        video_path: Optional[str] = None,
        youtube_url: Optional[str] = None
    ) -> UploadMethod:
        """Wählt automatisch die Upload-Methode basierend auf der Eingabe"""

        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"Dateigröße {file_size / 1024 / 1024 / 1024:.2f}GB "
                    f"überschreitet das 2GB Limit. Bitte auf YouTube hochladen und URL verwenden."
                )

        raise ValueError("Es muss entweder video_path oder youtube_url angegeben werden")

    def _analyze_inline(
        self,
        video_path: str,
        prompt: str,
        media_resolution: str = "standard"
    ) -> str:
        """Analyse per Inline-Upload"""
        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:
        """Analyse per Files API Upload"""
        # Datei hochladen
        video_file = genai.upload_file(path=video_path)

        # Warten auf Abschluss der Verarbeitung
        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("Dateiverarbeitung fehlgeschlagen")

        # Video analysieren
        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:
        """Analyse per 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:
        """
        Videoinhalt analysieren

        Args:
            prompt: Eingabeaufforderung für die Analyse
            video_path: Lokaler Pfad zum Video (optional)
            youtube_url: YouTube Video URL (optional)
            media_resolution: Auflösung ("low"/"standard"/"high")
            force_method: Erzwungene Upload-Methode (optional)

        Returns:
            VideoAnalysisResult Objekt
        """

        try:
            # Upload-Methode wählen
            method = force_method or self._choose_method(video_path, youtube_url)
            print(f"Verwendete Upload-Methode: {method.value}")

            # Analyse ausführen
            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)
            )


# Anwendungsbeispiel
if __name__ == "__main__":
    analyzer = GeminiVideoAnalyzer(api_key="your-api-key")

    # Beispiel 1: Kleines Video (verwendet automatisch Inline-Upload)
    result = analyzer.analyze(
        prompt="Beschreibe bitte den Videoinhalt",
        video_path="small_clip.mp4"
    )

    # Beispiel 2: Großes Video (verwendet automatisch Files API)
    result = analyzer.analyze(
        prompt="Analysiere die wichtigsten Wissenspunkte dieses Schulungsvideos",
        video_path="training_video_500mb.mp4",
        media_resolution="low"  # Niedrige Auflösung für lange Videos, um Kosten zu sparen
    )

    # Beispiel 3: YouTube-Video
    result = analyzer.analyze(
        prompt="Fasse die Kernaussagen dieses Videos zusammen",
        youtube_url="https://www.youtube.com/watch?v=VIDEO_ID"
    )

    if result.success:
        print(f"Analysemethode: {result.method.value}")
        print(f"Ergebnis:\n{result.content}")
    else:
        print(f"Analyse fehlgeschlagen: {result.error}")

Häufig gestellte Fragen (FAQ) zum Gemini Videoverständnis

# FFmpeg: Video auf unter 1 GB komprimieren
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# Video in 10-Minuten-Segmente aufteilen
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "Bitte analysiere den Inhalt des Videos zwischen 05:30 und 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"
        }
    }
)

Zusammenfassung der Gemini-Lösungen für die Verarbeitung extragroßer Videos

Zusammenfassung der Lösungen für extragroße Videos Wählen Sie die optimale Lösung basierend auf Videogröße und Anwendungsfall

Base64-Inline

≤ 100MB

✓ Einzelne API-Anfrage ✓ Einfachster Code ✓ Keine Dateiverwaltung ✗ Nicht wiederverwendbar ✗ Hohe Speicherauslastung

Files API

≤ 2GB

✓ Unterstützt große Dateien ✓ URI wiederverwendbar ✓ Private Dateien ✓ Spart Uploads ✗ Zweistufiger Prozess

YouTube URL

Unbegrenzt

✓ Kein Größenlimit ✓ Kein Upload nötig ✓ Native Google-Integration ✓ Support für 6h Videos ✗ Nur öffentliche Videos

Lösung nach Szenario wählen

Anwendungsfall Empfehlung Grund

Schnelle Kurzvideo-Tests Base64-Inline Einfacher Code, ein Schritt

Analyse privater Großvideos Files API Einmaliger Upload, oft nutzen

Extralange öffentliche Videos YouTube URL Unbegrenzt, native Integration

Gemini-Videoverständnis über APIYI apiyi.com nutzen – alle 3 Methoden unterstützt

Dieser Artikel stellt drei vollständige Ansätze für die Verarbeitung von extragroßen Videodateien vor:

Entscheidungsbaum für die Lösungswahl

Ist das Video bereits auf YouTube?
├── Ja → YouTube URL verwenden (am einfachsten)
└── Nein → Videogröße?
    ├── ≤ 100 MB → Base64-Inline (einzelne Anfrage)
    ├── 100 MB - 2 GB → Files API (unterstützt Wiederverwendung)
    └── > 2 GB → Auf YouTube hochladen oder komprimieren/aufteilen

🎯 Abschließende Empfehlung: Für extragroße Videodateien sollten Sie die YouTube-URL-Lösung bevorzugen. Sie bietet nicht nur keine Beschränkung der Dateigröße, sondern nutzt auch die native Google-Integration für minimale Latenzzeiten. Wir empfehlen, die Gemini-Videoverständnis-Funktionen über APIYI (apiyi.com) aufzurufen, um von günstigeren Preisen und einem stabilen Service zu profitieren.

Dieser Artikel wurde vom APIYI-Technikteam verfasst. Für weitere Tipps zur Nutzung von multimodalen KI-APIs besuchen Sie bitte apiyi.com für technischen Support.