Полное руководство по API для анализа огромных видеофайлов: 3 способа обработки видео от 100 МБ до 2 ГБ

Обработка сверхбольших видеофайлов для понимания ИИ всегда была головной болью для разработчиков: тайм-ауты при загрузке из-за размера, переполнение памяти при кодировании в base64 и ошибки 413 от API. Хорошие новости: в январе 2026 года Google значительно расширил возможности Gemini API по работе с файлами. Лимит встроенной загрузки (inline) вырос с 20 МБ до 100 МБ, Files API теперь поддерживает до 2 ГБ, а также появилась функция прямого анализа видео по ссылке с YouTube. В этой статье мы подробно разберем три способа работы с большими видео, чтобы вы могли выбрать оптимальный технический путь.

Ключевая ценность: прочитав этот материал, вы освоите готовые решения для обработки видео размером от 100 МБ до 2 ГБ и сможете выбирать лучший способ загрузки в зависимости от объема файла, частоты использования и бизнес-задач.

Обзор способов загрузки больших видеофайлов в Gemini

Прежде чем углубляться в детали, давайте сравним три способа загрузки видео, которые предлагает Gemini:

🎯 Главный совет: Если видео весит больше 100 МБ, в первую очередь рассмотрите загрузку на YouTube (анализ по ссылке) или использование Files API. Оба способа стабильно справляются с файлами объемом в несколько гигабайт.

Модели Gemini с поддержкой понимания видео

Вариант 1 для анализа видео в Gemini: прямой анализ по YouTube URL

Для работы с очень большими видеофайлами самое элегантное решение — загрузить их на YouTube и позволить Gemini анализировать их напрямую по ссылке. Это нативная интеграция от Google, которая избавляет от необходимости передавать тяжелые файлы через API.

Основные преимущества схемы с YouTube URL

Пример кода для анализа видео по 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)

Ограничения схемы с YouTube URL

💡 Полезный совет: Если видео содержит конфиденциальную информацию, установите на YouTube статус «Доступ по ссылке» (Unlisted). Так видео не появится в поиске, но Gemini API сможет его проанализировать. При вызове через APIYI (apiyi.com) функция анализа YouTube URL работает в полном объеме.

Пример запроса по временным меткам

Gemini умеет искать информацию в конкретных фрагментах видео:

# Запрос контента по конкретным временным меткам
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"
                    }
                }
            ]
        }
    ]
)

Вариант 2 для анализа видео в Gemini: загрузка через Files API

Для приватных видео, которые нельзя выкладывать на YouTube (например, внутренние тренинги или коммерческая тайна), Files API — лучший выбор для файлов размером от 100 МБ до 2 ГБ.

Процесс работы с Files API

Локальный файл → Загрузка через Files API → Получение file_uri → Запрос на анализ

Полный пример кода для 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
    Поддерживаются файлы до 2 ГБ
    """
    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)

Управление файлами в 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} МБ")
    print(f"  Статус: {file.state.name}")
    print()

# Удаление ненужных файлов (для экономии места)
genai.delete_file(file.name)

🎯 Оптимизация затрат: Файлы, загруженные через Files API, можно использовать в нескольких запросах повторно, не тратя время на новую загрузку. Если вам нужно проанализировать одно и то же видео несколько раз, сохраните file_uri. Платформа APIYI (apiyi.com) также полностью поддерживает функционал Files API.

Вариант 3 для работы с видео в Gemini: Inline-загрузка через Base64

Для небольших видеороликов (до 100 МБ) inline-загрузка через Base64 — это самый простой способ, так как всё выполняется за один вызов API.

Пример кода для 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"  # Унифицированный интерфейс APIYI
)

def analyze_video_inline(video_path: str, prompt: str) -> str:
    """
    Inline-загрузка видео для анализа (подходит для видео ≤100 МБ)
    """
    # Чтение и кодирование видео
    video_bytes = Path(video_path).read_bytes()
    video_size_mb = len(video_bytes) / 1024 / 1024

    if video_size_mb > 100:
        raise ValueError(f"Размер видео {video_size_mb:.2f} МБ превышает лимит 100 МБ, используйте Files API")

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

    # Определение 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",  # Для видео также используется тип image_url
                        "image_url": {
                            "url": f"data:{mime_type};base64,{video_base64}"
                        }
                    }
                ]
            }
        ],
        max_tokens=4096
    )

    return response.choices[0].message.content

# Пример использования
result = analyze_video_inline(
    "short_clip.mp4",
    "Опиши, пожалуйста, основное содержание этого видеофрагмента"
)
print(result)

На что стоит обратить внимание при использовании Base64

Расчет токенов и оптимизация затрат в Gemini Video

Понимание правил расчета токенов критически важно для контроля ваших расходов.

Формула расчета токенов для видео в Gemini

Расход токенов для видео разной длительности

Настройка низкого разрешения для экономии

# Используем низкое разрешение для длинных видео, чтобы сэкономить 67% токенов
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[...],
    extra_body={
        "media_resolution": "low"  # 360p, 100 токенов/сек
    }
)

💰 Оптимизация затрат: Для задач по смысловому анализу (например, резюме видео или классификация контента) низкого разрешения обычно вполне достаточно. Высокое разрешение требуется только тогда, когда нужно распознать мелкие детали (текст, мелкие объекты). Используя функции видеоаналитики Gemini через APIYI (apiyi.com), вы можете получить более выгодные цены.

Gemini: работа со сверхбольшими видео — готовый воркфлоу

Ниже представлено полное решение, которое автоматически выбирает оптимальный способ загрузки в зависимости от размера видеофайла.

"""
Полное решение для анализа сверхбольших видеофайлов через 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} ГБ "
                    f"превышает лимит 2 ГБ. Пожалуйста, загрузите его на YouTube и используйте URL."
                )

        raise ValueError("Необходимо указать video_path или youtube_url")

    def _analyze_inline(
        self,
        video_path: str,
        prompt: str,
        media_resolution: str = "standard"
    ) -> str:
        """Анализ через 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:
        """Анализ через 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: URL видео на YouTube (опционально)
            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: Короткое видео (автоматически через inline-загрузку)
    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 по анализу видео в Gemini

# Сжатие видео до размера менее 1 ГБ с помощью FFmpeg
ffmpeg -i input.mp4 -vcodec h264 -acodec aac -fs 1G output.mp4

# Разделение видео на фрагменты по 10 минут
ffmpeg -i input.mp4 -c copy -segment_time 600 -f segment output_%03d.mp4

prompt = "Проанализируй содержание видео с 05:30 по 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"
        }
    }
)

Итоги: способы обработки огромных видео в Gemini

Способы обработки огромных видео Выбираем лучший вариант в зависимости от размера и задачи

Base64 Inline

≤ 100 МБ

✓ Один API-запрос ✓ Простейший код ✓ Без управления файлами ✗ Нельзя переиспользовать ✗ Высокий расход памяти

Files API

≤ 2 ГБ

✓ Для больших файлов ✓ URI можно использовать повторно ✓ Поддержка приватных файлов ✓ Экономия на загрузке ✗ Нужно два этапа

YouTube URL

Без лимитов

✓ Нет ограничений на размер ✓ Не нужно загружать по API ✓ Нативная интеграция Google ✓ Поддержка видео до 6 часов ✗ Только публичные видео

Выбор по сценарию использования

Сценарий Рекомендация Причина

Быстрый тест коротких видео Base64 Inline Простой код, один шаг

Повторный анализ приватных видео Files API Загрузил один раз — используй многократно

Анализ длинных публичных видео YouTube URL Без лимитов, самая быстрая интеграция

Все три способа доступны через APIYI apiyi.com для анализа видео в Gemini

В этой статье мы разобрали три основных способа работы с тяжелыми видеофайлами:

Как выбрать подходящий вариант?

Видео уже загружено на YouTube?
├── Да → Используйте YouTube URL (проще всего)
└── Нет → Какой размер файла?
    ├── ≤ 100 МБ → Base64 Inline (один запрос)
    ├── 100 МБ - 2 ГБ → Files API (с переиспользованием)
    └── > 2 ГБ → Загрузите на YouTube или сожмите/разрежьте файл

🎯 Итоговый совет: Для действительно больших файлов лучше всего подходит схема с YouTube URL. У этого способа нет ограничений по весу, а нативная интеграция с сервисами Google обеспечивает минимальные задержки. Рекомендуем использовать APIYI (apiyi.com) для доступа к функциям анализа видео в Gemini — это выгодно, стабильно и удобно.

Статья подготовлена технической командой APIYI. Еще больше фишек по работе с мультимодальными моделями ищите на apiyi.com.