Guía completa de API para la comprensión de archivos de video extragrandes: 3 métodos para procesar videos de 100 MB a 2 GB

El procesamiento y la comprensión de archivos de video de gran tamaño con IA ha sido durante mucho tiempo un dolor de cabeza para los desarrolladores: los archivos son demasiado pesados y causan tiempos de espera agotados (timeout), la codificación en base64 provoca desbordamientos de memoria y las interfaces devuelven errores 413. La buena noticia es que, en enero de 2026, Google mejoró significativamente la capacidad de procesamiento de archivos de la API de Gemini: el límite de carga en línea aumentó de 20 MB a 100 MB, la Files API ahora admite hasta 2 GB y se ha añadido la función de análisis directo mediante URL de YouTube. En este artículo explicaremos detalladamente estas tres soluciones para manejar videos de gran tamaño, ayudándote a elegir la ruta técnica que mejor se adapte a tus necesidades.

Valor principal: Al finalizar este artículo, dominarás soluciones completas para procesar videos de entre 100 MB y 2 GB, y sabrás elegir el método de carga óptimo según el tamaño del video, la frecuencia de uso y el escenario de negocio.

Vistazo rápido a las soluciones de carga de videos grandes en Gemini

Antes de profundizar en los detalles técnicos, conoce las tres formas que ofrece Gemini para cargar videos:

🎯 Recomendación clave: Para archivos de video que superen los 100 MB, prioriza subirlos a YouTube para analizarlos mediante URL o utiliza la Files API para la carga. Ambos métodos permiten manejar de forma estable archivos de video de varios gigabytes.

Modelos de Gemini compatibles con la comprensión de video

Gemini Solución de Comprensión de Video 1: Análisis Directo por URL de YouTube

Para archivos de video extra grandes, la solución más elegante es subirlos a YouTube y luego permitir que Gemini los analice directamente a través de la URL. Esta es una integración nativa de Google que no requiere transferencia manual de archivos.

Ventajas clave de la solución mediante URL de YouTube

Ejemplo de código para comprensión de video vía URL de YouTube

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Usando la interfaz unificada de APIYI
)

# Analizar video a través de una URL de YouTube
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Por favor, analiza el contenido principal de este video y enumera los momentos clave con sus eventos correspondientes"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ],
    max_tokens=4096
)

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

Limitaciones de la solución mediante URL de YouTube

💡 Consejo práctico: Si el contenido del video es sensible, puedes configurarlo en YouTube como "Oculto" (Unlisted). De esta manera, solo quienes tengan el enlace podrán acceder, pero la API de Gemini podrá analizarlo normalmente. Esta funcionalidad de URL de YouTube también es compatible cuando realizas llamadas a través de APIYI (apiyi.com).

Ejemplo de consulta por marca de tiempo

Gemini permite realizar consultas precisas sobre momentos específicos del video:

# Consultar el contenido en momentos específicos del video
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "¿Podrías decirme qué se muestra exactamente en los minutos 02:30 y 05:45 de este video?"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=VIDEO_ID"
                    }
                }
            ]
        }
    ]
)

Gemini Solución de Comprensión de Video 2: Subida con Files API

Para videos privados que no pueden subirse a YouTube (como capacitaciones internas o secretos comerciales), la Files API es la mejor opción para manejar archivos de entre 100 MB y 2 GB.

Flujo de subida con Files API

Archivo de video local → Subida vía Files API → Obtener file_uri → Iniciar solicitud de análisis

Ejemplo de código completo con Files API

import google.generativeai as genai
import time

# Configuración de la API
genai.configure(api_key="YOUR_API_KEY")

def upload_large_video(video_path: str) -> str:
    """
    Sube un archivo de video grande a la Files API de Gemini
    Soporta archivos de hasta 2GB
    """
    print(f"Subiendo video: {video_path}")

    # Subir archivo
    video_file = genai.upload_file(
        path=video_path,
        display_name="large_video"
    )

    # Esperar a que se complete el procesamiento del archivo
    while video_file.state.name == "PROCESSING":
        print("Procesando...")
        time.sleep(5)
        video_file = genai.get_file(video_file.name)

    if video_file.state.name == "FAILED":
        raise ValueError(f"Error al procesar el archivo: {video_file.state.name}")

    print(f"¡Subida exitosa! URI: {video_file.uri}")
    return video_file.uri

def analyze_video(file_uri: str, prompt: str) -> str:
    """
    Analizar un video ya subido
    """
    model = genai.GenerativeModel("gemini-3-pro-preview")

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

    return response.text

# Ejemplo de uso
video_uri = upload_large_video("/ruta/al/video_grande.mp4")
result = analyze_video(
    video_uri,
    "Por favor, analiza detalladamente el contenido de este video, incluyendo escenas principales, actividades de las personas e información clave"
)
print(result)

Gestión de archivos en Files API

# Listar todos los archivos subidos
for file in genai.list_files():
    print(f"Nombre: {file.name}")
    print(f"  URI: {file.uri}")
    print(f"  Tamaño: {file.size_bytes / 1024 / 1024:.2f} MB")
    print(f"  Estado: {file.state.name}")
    print()

# Eliminar archivos que ya no son necesarios (para ahorrar espacio)
genai.delete_file(file.name)

🎯 Optimización de costos: Los archivos subidos a la Files API pueden reutilizarse en múltiples solicitudes, evitando subidas repetitivas. Se recomienda que para videos que necesiten múltiples análisis, se suban una sola vez y se guarde la file_uri para usos posteriores. Todas las funciones de la Files API están disponibles al llamar a través de la plataforma APIYI (apiyi.com).

Opción 3 para la comprensión de video con Gemini: Carga en línea Base64

Para videos pequeños de menos de 100 MB, la carga en línea mediante Base64 es la forma más sencilla, ya que solo requiere una única llamada a la API para completarse.

Ejemplo de código para carga en línea Base64

import openai
import base64
from pathlib import Path

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

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    Carga en línea un video para su análisis (adecuado para videos ≤100 MB)
    """
    # Leer y codificar el video
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"El tamaño del video {video_size_mb:.2f} MB supera el límite de 100 MB, por favor utiliza la Files API")

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

    # Determinar el tipo 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",  # Los videos también utilizan el tipo image_url
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# Ejemplo de uso
result = analyze_video_inline(
    "short_clip.mp4",
    "Por favor, describe el contenido principal de este fragmento de video"
)
print(result)

Consideraciones sobre la carga en línea Base64

Cálculo de Tokens y optimización de costos en Gemini Video

Entender las reglas de cálculo de tokens es fundamental para controlar los costos.

Fórmula de cálculo de tokens de video en Gemini

Consumo de tokens según la duración del video

Configuración de baja resolución para ahorrar costos

# Usar baja resolución para procesar videos largos, ahorrando un 67% de tokens
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # 360p, 100 tokens/segundo
    }
)

💰 Optimización de costos: Para tareas de comprensión de contenido (como resúmenes de video o clasificación de contenido), usar baja resolución suele ser suficiente. La alta resolución solo es necesaria cuando se requiere identificar detalles específicos (como texto u objetos pequeños). Al utilizar las funciones de comprensión de video de Gemini a través de APIYI (apiyi.com), puedes obtener precios mucho más competitivos.

Práctica de procesamiento de videos gigantes con Gemini: flujo de trabajo completo

A continuación, presentamos una solución completa que selecciona automáticamente el mejor método de carga según el tamaño del 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}")

Preguntas frecuentes sobre la comprensión de video con Gemini

# Comprimir video con FFmpeg para que ocupe menos de 1 GB
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# Dividir el video en fragmentos de 10 minutos
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "Analiza el contenido del video entre el minuto 05:30 y el 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"
        }
    }
)

Resumen de las 3 soluciones completas para procesar archivos de video de gran tamaño:

Resumen de Soluciones para Videos Gigantes Elige la mejor opción según el tamaño y el caso de uso

Base64 Inline

≤ 100MB

✓ Una sola solicitud de API ✓ Código más sencillo ✓ Sin gestión de archivos ✗ No reutilizable ✗ Alto uso de memoria

Files API

≤ 2GB

✓ Soporta archivos grandes ✓ URI reutilizable ✓ Soporte archivos privados ✓ Ahorra resubidas ✗ Requiere dos pasos

YouTube URL

Ilimitado

✓ Sin límite de tamaño ✓ Sin necesidad de subir ✓ Integración nativa Google ✓ Soporta videos de 6h ✗ Solo videos públicos/ocultos

Elegir plan según el escenario

Escenario Plan recomendado Razón

Pruebas rápidas videos cortos Base64 Inline Código simple, un solo paso

Análisis recurrente videos grandes Files API Sube una vez, usa muchas

Videos públicos muy largos YouTube URL Sin límites, integración más rápida

Usa Gemini para comprensión de video vía APIYI apiyi.com, compatible con los tres métodos

Flujo de decisión para elegir una solución

¿El video ya está en YouTube?
├── Sí → Usar YouTube URL (el más sencillo)
└── No → ¿Tamaño del video?
    ├── ≤ 100MB → Base64 Inline (una sola solicitud)
    ├── 100MB-2GB → Files API (permite reutilización)
    └── > 2GB → Subir a YouTube o comprimir/dividir

🎯 Recomendación final: Para archivos de video gigantes, prioriza la solución de YouTube URL; no solo elimina los límites de tamaño, sino que aprovecha la integración nativa de Google para minimizar la latencia. Te recomendamos usar las funciones de comprensión de video de Gemini a través de APIYI (apiyi.com) para obtener precios más competitivos y un servicio estable.

Este artículo fue escrito por el equipo técnico de APIYI. Para conocer más trucos sobre el uso de APIs de IA multimodales, visita apiyi.com para obtener soporte técnico.