Guia Completo da API de Compreensão de Arquivos de Vídeo Extragrandes: 3 Métodos para Processar Vídeos de 100MB a 2GB

A compreensão de arquivos de vídeo gigantes via IA sempre foi uma dor de cabeça para os desenvolvedores — arquivos grandes demais que causam timeout no upload, estouro de memória com codificação base64 e erros 413 no retorno da interface. A boa notícia é que, em janeiro de 2026, o Google aumentou significativamente a capacidade de processamento de arquivos da API do Gemini: o limite de upload inline subiu de 20MB para 100MB, a Files API agora suporta até 2GB, e foi adicionada a funcionalidade de análise direta via URL do YouTube. Este artigo detalha as 3 soluções para lidar com vídeos gigantes, ajudando você a escolher a melhor rota tecnológica.

Valor Principal: Ao ler este artigo, você dominará o guia completo para lidar com vídeos gigantes de 100MB a 2GB, sendo capaz de escolher o método de upload ideal com base no tamanho do vídeo, frequência de uso e cenário de negócio.

Resumo das Soluções de Upload de Vídeos Gigantes no Gemini

Antes de mergulharmos nos detalhes técnicos, conheça as três formas de upload de vídeo oferecidas pelo Gemini:

🎯 Sugestão Principal: Para arquivos de vídeo acima de 100MB, priorize o upload para o YouTube para análise via URL, ou utilize a Files API. Ambos os métodos conseguem processar de forma estável arquivos na casa dos GBs.

Modelos com Suporte para Compreensão de Vídeo no Gemini

Solução 1 para Entendimento de Vídeo no Gemini: Análise Direta via URL do YouTube

Para arquivos de vídeo gigantescos, a solução mais elegante é fazer o upload para o YouTube e deixar o Gemini analisar diretamente via URL. Essa é uma integração nativa do Google, o que significa que não há necessidade de transferência manual de arquivos entre servidores.

Principais Vantagens da Solução via URL do YouTube

Exemplo de Código para Entendimento de Vídeo via URL do YouTube

import openai

client = openai.OpenAI(
    api_key="SUA_CHAVE_API",
    base_url="https://api.apiyi.com/v1"  # Usando a interface unificada da APIYI
)

# Analisando vídeo através da URL do YouTube
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Por favor, analise o conteúdo principal deste vídeo e liste os pontos temporais importantes com seus respectivos eventos."
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=ID_DO_VIDEO"
                    }
                }
            ]
        }
    ],
    max_tokens=4096
)

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

Limitações da Solução via URL do YouTube

💡 Dica prática: Se o conteúdo do vídeo for sensível ou privado, você pode configurá-lo no YouTube como "Não listado" (Unlisted). Dessa forma, apenas quem tem o link consegue acessar, e a API do Gemini conseguirá processá-lo normalmente. Essa funcionalidade de URL do YouTube também funciona perfeitamente ao fazer chamadas através da APIYI (apiyi.com).

Exemplo de Consulta por Timestamp

O Gemini permite fazer consultas precisas sobre momentos específicos do vídeo:

# Consultando conteúdo em pontos específicos do vídeo
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Pode me dizer o que está sendo mostrado nos tempos 02:30 e 05:45 deste vídeo?"
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://www.youtube.com/watch?v=ID_DO_VIDEO"
                    }
                }
            ]
        }
    ]
)

Solução 2 para Entendimento de Vídeo no Gemini: Upload via Files API

Para vídeos privados que não podem subir para o YouTube (como treinamentos internos ou segredos industriais), a Files API é a melhor escolha para lidar com arquivos entre 100MB e 2GB.

Fluxo de Upload da Files API

Vídeo Local → Upload via Files API → Obter file_uri → Criar requisição de análise

Exemplo Completo de Código com Files API

import google.generativeai as genai
import time

# Configuração da API
genai.configure(api_key="SUA_CHAVE_API")

def upload_large_video(video_path: str) -> str:
    """
    Faz o upload de vídeos grandes para a Gemini Files API
    Suporta arquivos de até 2GB
    """
    print(f"Fazendo upload do vídeo: {video_path}")

    # Upload do arquivo
    video_file = genai.upload_file(
        path=video_path,
        display_name="video_grande"
    )

    # Aguarda o processamento do arquivo pelo servidor
    while video_file.state.name == "PROCESSING":
        print("Processando...")
        time.sleep(5)
        video_file = genai.get_file(video_file.name)

    if video_file.state.name == "FAILED":
        raise ValueError(f"Falha no processamento do arquivo: {video_file.state.name}")

    print(f"Upload concluído! URI: {video_file.uri}")
    return video_file.uri

def analyze_video(file_uri: str, prompt: str) -> str:
    """
    Analisa um vídeo que já foi carregado
    """
    model = genai.GenerativeModel("gemini-3-pro-preview")

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

    return response.text

# Exemplo de uso
video_uri = upload_large_video("/caminho/para/video_grande.mp4")
result = analyze_video(
    video_uri,
    "Por favor, analise detalhadamente o conteúdo deste vídeo, descrevendo as cenas principais, atividades das pessoas e informações cruciais."
)
print(result)

Gerenciamento de Arquivos na Files API

# Listar todos os arquivos carregados na sua conta
for file in genai.list_files():
    print(f"Nome: {file.name}")
    print(f"  URI: {file.uri}")
    print(f"  Tamanho: {file.size_bytes / 1024 / 1024:.2f} MB")
    print(f"  Status: {file.state.name}")
    print()

# Deletar arquivos que não são mais necessários (para limpar o armazenamento)
genai.delete_file(file.name)

🎯 Otimização de Custos: Arquivos enviados via Files API podem ser reutilizados em múltiplas requisições, evitando o custo de tempo e banda de novos uploads. Se você precisa analisar o mesmo vídeo várias vezes, faça o upload uma vez e salve a file_uri. A plataforma APIYI (apiyi.com) também oferece suporte total às funcionalidades da Files API.

Solução 3 para Compreensão de Vídeo no Gemini: Upload Inline via Base64

Para vídeos pequenos de até 100 MB, o upload inline via Base64 é a maneira mais simples, exigindo apenas uma única chamada de API para ser concluído.

Exemplo de Código para Upload Inline via Base64

import openai
import base64
from pathlib import Path

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

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    Faz o upload inline de vídeo para análise (indicado para vídeos ≤ 100 MB)
    """
    # Lê e codifica o vídeo
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"O tamanho do vídeo {video_size_mb:.2f}MB excede o limite de 100MB. Por favor, use a Files API.")

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

    # Determina o 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",  # Vídeos também utilizam o tipo image_url
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# Exemplo de uso
result = analyze_video_inline(
    "short_clip.mp4",
    "Por favor, descreva o conteúdo principal deste clipe de vídeo"
)
print(result)

Considerações Importantes sobre Upload Inline via Base64

Cálculo de Tokens e Otimização de Custos no Gemini para Vídeo

Entender as regras de cálculo de tokens é fundamental para manter os custos sob controle.

Fórmula de Cálculo de Tokens de Vídeo no Gemini

Consumo de Tokens para Diferentes Durações de Vídeo

Configurando Baixa Resolução para Economizar

# Usa baixa resolução para processar vídeos longos, economizando 67% de tokens
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # 360p, 100 tokens/segundo
    }
)

💰 Otimização de custos: Para tarefas de compreensão de conteúdo (como resumos de vídeo ou classificação), a baixa resolução geralmente é suficiente. A alta resolução só é necessária quando é preciso identificar detalhes minuciosos (como textos pequenos ou objetos distantes). Ao utilizar as funcionalidades de compreensão de vídeo do Gemini via APIYI (apiyi.com), você garante acesso a preços mais competitivos.

Guia Prático de Processamento de Vídeos Gigantes com Gemini: Workflow Completo

Abaixo está uma solução completa que escolhe automaticamente o melhor método de upload com base no tamanho do vídeo.

"""
Solução completa para compreensão de arquivos de vídeo gigantes no Gemini
Escolha automática do melhor método de upload com base no tamanho do arquivo
"""

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:
    """
    Analisador de vídeo inteligente
    Seleciona automaticamente o melhor método para lidar com vídeos de vários tamanhos
    """

    # Limites de tamanho de arquivo (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:
        """Obtém o tamanho do arquivo"""
        return Path(video_path).stat().st_size

    def _choose_method(
        self,
        video_path: Optional[str] = None,
        youtube_url: Optional[str] = None
    ) -> UploadMethod:
        """Escolhe o método de upload automaticamente com base no input"""

        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"O tamanho do arquivo {file_size / 1024 / 1024 / 1024:.2f}GB "
                    f"excede o limite de 2GB. Por favor, suba para o YouTube e use a URL para análise."
                )

        raise ValueError("É necessário fornecer video_path ou youtube_url")

    def _analyze_inline(
        self,
        video_path: str,
        prompt: str,
        media_resolution: str = "standard"
    ) -> str:
        """Análise via upload inline"""
        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:
        """Análise via Files API"""
        # Upload do arquivo
        video_file = genai.upload_file(path=video_path)

        # Aguarda o processamento
        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("Falha no processamento do arquivo")

        # Analisa o vídeo
        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:
        """Análise via URL do YouTube"""
        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:
        """
        Analisa o conteúdo do vídeo

        Args:
            prompt: comando de análise
            video_path: Caminho do vídeo local (opcional)
            youtube_url: URL do vídeo no YouTube (opcional)
            media_resolution: Resolução ("low"/"standard"/"high")
            force_method: Forçar um método de upload específico (opcional)

        Returns:
            Objeto VideoAnalysisResult
        """

        try:
            # Escolhe o método de upload
            method = force_method or self._choose_method(video_path, youtube_url)
            print(f"Usando método de upload: {method.value}")

            # Executa a análise
            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)
            )


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

    # Exemplo 1: Vídeo pequeno (usa upload inline automaticamente)
    result = analyzer.analyze(
        prompt="Por favor, descreva o conteúdo do vídeo",
        video_path="small_clip.mp4"
    )

    # Exemplo 2: Vídeo grande (usa Files API automaticamente)
    result = analyzer.analyze(
        prompt="Analise os principais pontos de conhecimento deste vídeo de treinamento",
        video_path="training_video_500mb.mp4",
        media_resolution="low"  # Usa baixa resolução para economizar em vídeos longos
    )

    # Exemplo 3: Vídeo do YouTube
    result = analyzer.analyze(
        prompt="Resuma a ideia central deste vídeo",
        youtube_url="https://www.youtube.com/watch?v=VIDEO_ID"
    )

    if result.success:
        print(f"Método de análise: {result.method.value}")
        print(f"Resultado:\n{result.content}")
    else:
        print(f"Falha na análise: {result.error}")

Perguntas Frequentes sobre Compreensão de Vídeo no Gemini

# Comprimir vídeo para menos de 1GB usando FFmpeg
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# Dividir o vídeo em segmentos de 10 minutos
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "Por favor, analise o conteúdo entre 05:30 e 08:45 do vídeo"

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

Resumo de Soluções do Gemini para Vídeos Gigantes

Este artigo apresenta 3 soluções completas para lidar com arquivos de vídeo extra grandes:

Fluxograma de Decisão para Escolha da Solução

O vídeo já está no YouTube?
├── Sim → Use YouTube URL (Mais simples)
└── Não → Qual o tamanho do vídeo?
    ├── ≤ 100MB → Base64 Inline (Requisição única)
    ├── 100MB-2GB → Files API (Suporta reutilização)
    └── > 2GB → Upload para YouTube ou comprimir/dividir

🎯 Sugestão Final: Para arquivos de vídeo gigantes, priorize a solução YouTube URL. Além de não ter limite de tamanho, ela aproveita a integração nativa do Google para garantir a menor latência possível. Recomendamos usar a APIYI em apiyi.com para acessar as funções de compreensão de vídeo do Gemini com preços mais competitivos e serviços estáveis.

Este artigo foi escrito pela equipe técnica da APIYI. Para mais dicas sobre APIs de IA multimodais, visite apiyi.com para suporte técnico.