Guide complet de l’API de compréhension de fichiers vidéo volumineux : 3 méthodes pour traiter des vidéos de 100 Mo à 2 Go

La compréhension par l'IA de fichiers vidéo ultra-volumineux a toujours été un casse-tête pour les développeurs : délais d'attente dépassés, débordements de mémoire avec l'encodage base64, erreurs 413… La bonne nouvelle, c'est qu'en janvier 2026, Google a considérablement boosté les capacités de traitement de fichiers de l'API Gemini : la limite d'upload en ligne est passée de 20 Mo à 100 Mo, l'API Files supporte désormais jusqu'à 2 Go, et une nouvelle fonction d'analyse directe via URL YouTube a été ajoutée. Cet article détaille ces trois solutions pour gérer les vidéos massives et vous aide à choisir la meilleure approche technique.

Valeur ajoutée : À la fin de cet article, vous maîtriserez les solutions complètes pour traiter des vidéos allant de 100 Mo à 2 Go, et saurez choisir la méthode d'upload optimale en fonction de la taille, de la fréquence d'utilisation et de votre cas d'usage.

Aperçu des solutions d'upload de vidéos volumineuses avec Gemini

Avant de plonger dans les détails techniques, voici les trois méthodes proposées par Gemini :

🎯 Conseil clé : Pour les fichiers vidéo de plus de 100 Mo, privilégiez l'analyse via URL YouTube ou l'utilisation de l'API Files. Ces deux méthodes permettent de traiter de manière stable des fichiers de l'ordre du Go.

Modèles supportant la compréhension vidéo

Option 1 pour la compréhension vidéo avec Gemini : analyse directe via URL YouTube

Pour les fichiers vidéo ultra-volumineux, la solution la plus élégante consiste à les uploader sur YouTube, puis à laisser Gemini les analyser directement via l'URL. Il s'agit d'une intégration native de Google, ce qui évite tout transfert de fichier fastidieux.

Avantages clés de la solution URL YouTube

Exemple de code pour l'analyse via URL YouTube

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)

Limitations de la solution URL YouTube

💡 Astuce pratique : Si le contenu de votre vidéo est confidentiel, vous pouvez la régler sur "Non répertoriée" (Unlisted) sur YouTube. Ainsi, seules les personnes disposant du lien peuvent y accéder, et l'API Gemini pourra toujours l'analyser normalement. Cette fonctionnalité est pleinement supportée via les appels API sur APIYI (apiyi.com).

Exemple de requête par horodatage

Gemini permet d'effectuer des requêtes précises sur des moments spécifiques de la vidéo :

# 查询视频特定时间点的内容
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"
                    }
                }
            ]
        }
    ]
)

Option 2 pour la compréhension vidéo avec Gemini : upload de fichiers via l'API Files

Pour les vidéos privées qui ne peuvent pas être hébergées sur YouTube (comme des formations internes ou des secrets industriels), l'API Files est la meilleure option pour traiter des fichiers allant de 100 Mo à 2 Go.

Flux de travail de l'API Files

Vidéo locale → Upload via Files API → Obtention du file_uri → Envoi de la requête d'analyse

Exemple de code complet avec l'API Files

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)

Gestion des fichiers avec l'API Files

# 列出所有已上传的文件
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)

🎯 Optimisation des coûts : Les fichiers uploadés via l'API Files peuvent être réutilisés pour plusieurs requêtes, évitant ainsi de répéter l'upload. Pour une vidéo que vous devez analyser sous plusieurs angles, uploadez-la une fois et conservez son file_uri. L'ensemble des fonctionnalités de l'API Files est également disponible via la plateforme APIYI (apiyi.com).

Solution 3 pour la compréhension vidéo avec Gemini : Téléchargement en ligne (Base64)

Pour les petites vidéos de moins de 100 Mo, le téléchargement en ligne en Base64 est la méthode la plus simple. Un seul appel API suffit pour tout gérer.

Exemple de code pour le téléchargement en ligne en Base64

import openai
import base64
from pathlib import Path

client = openai.OpenAI(
    api_key="VOTRE_CLÉ_API",
    base_url="https://api.apiyi.com/v1"  # Interface unifiée APIYI
)

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    Analyse d'une vidéo via téléchargement en ligne (adapté aux vidéos ≤ 100 Mo)
    """
    # Lecture et encodage de la vidéo
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"La taille de la vidéo ({video_size_mb:.2f} Mo) dépasse la limite de 100 Mo. Veuillez utiliser l'API Files.")

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

    # Détermination du type 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",  # Les vidéos utilisent également le type image_url
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# Exemple d'utilisation
result = analyze_video_inline(
    "short_clip.mp4",
    "Décris le contenu principal de cet extrait vidéo"
)
print(result)

Points de vigilance pour le téléchargement en ligne en Base64

Calcul des tokens et optimisation des coûts pour la compréhension vidéo avec Gemini

Comprendre les règles de calcul des tokens est essentiel pour maîtriser votre budget.

Formule de calcul des tokens vidéo Gemini

Consommation de tokens selon la durée de la vidéo

Configurer une basse résolution pour réduire les coûts

# Utilisation d'une basse résolution pour les vidéos longues, économie de 67 % de tokens
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # 360p, 100 tokens/seconde
    }
)

💰 Optimisation des coûts : Pour les tâches de compréhension globale (comme les résumés vidéo ou la classification de contenu), la basse résolution est généralement amplement suffisante. La haute résolution n'est vraiment nécessaire que si vous devez identifier des détails précis (comme du texte à l'écran ou de petits objets). En passant par APIYI (apiyi.com) pour utiliser les fonctionnalités vidéo de Gemini, vous pouvez bénéficier de tarifs plus avantageux.

Pratique du traitement de vidéos volumineuses avec Gemini : Le workflow complet

Voici une solution complète pour choisir automatiquement la meilleure méthode d'importation en fonction de la taille de votre vidéo.

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

FAQ sur la compréhension vidéo avec Gemini

# Compresser une vidéo avec FFmpeg pour qu'elle fasse moins de 1 Go
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# Diviser une vidéo en segments de 10 minutes
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "Analyse le contenu de la vidéo entre 05:30 et 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"
        }
    }
)

Synthèse des solutions de traitement vidéo volumineux avec Gemini

Cet article présente les 3 solutions complètes pour traiter des fichiers vidéo volumineux :

Processus de décision pour choisir une solution

La vidéo est-elle déjà sur YouTube ?
├── Oui → Utiliser l'URL YouTube (plus simple)
└── Non → Taille de la vidéo ?
    ├── ≤ 100 Mo → Base64 Inline (requête unique)
    ├── 100 Mo - 2 Go → Files API (réutilisable)
    └── > 2 Go → Upload sur YouTube ou compression/découpage

🎯 Conseil final : Pour les fichiers vidéo volumineux, privilégiez l'option URL YouTube. Non seulement elle n'impose aucune limite de taille, mais elle bénéficie également de l'intégration native de Google pour une latence minimale. Nous vous recommandons d'appeler les fonctionnalités de compréhension vidéo de Gemini via APIYI (apiyi.com) pour bénéficier de tarifs avantageux et d'un service stable.

Cet article a été rédigé par l'équipe technique d'APIYI. Pour plus d'astuces sur l'utilisation des API d'IA multimodale, rendez-vous sur apiyi.com pour obtenir du support technique.