Skip to main content
APIYI предоставляет понимание видео через мультимодальные модели Gemini: по одному prompt модель «просматривает» сцены, действия, текст на экране и аудио в видео и может ссылаться на ключевые моменты по timestamp. На этой странице описаны поддерживаемые модели, способы ввода видео, которые действительно работают, и ограничения, на которых люди часто спотыкаются.
Сначала прочитайте это: видео можно передать только через Base64 inline (весь запрос ≤ 20 MB) или ссылку YouTube (нативный формат Gemini). Передача обычного публичного video URL (например, https://example.com/demo.mp4) возвращает Request contains an invalid argument —— это Google отклоняет прямые ссылки, а не блокировка со стороны APIYI. См. «Способы ввода видео» ниже.

Визуальное тестирование API

Загрузите видео и протестируйте эндпоинт понимания в визуальном инструменте тестирования iCover.

Поддерживаемые модели

Стабильные классические модели gemini-2.5-pro (контекстное окно 2M) и gemini-2.5-flash по-прежнему доступны. См. Модели и тарификация для полной информации о тарификации.

Методы ввода видео

Именно здесь возникает большинство проблем. Проверьте таблицу ниже, чтобы убедиться, что ваш метод ввода поддерживается:
Ограничение 20 MB: При использовании Base64 весь body запроса (включая закодированное видео) должен оставаться меньше 20 MB. Для видео размером более 20 MB у вас есть только такие варианты: ① использовать ссылку YouTube; ② сжать / обрезать видео локально до менее чем 20 MB перед кодированием в base64.

Быстрый старт: встроенный Base64 (формат, совместимый с OpenAI)

Самый распространенный подход: прочитайте локальное видео → закодируйте его в base64 → передайте его в поле image_url.
Эквивалентный curl (замените <BASE64_VIDEO> на строку base64 видео; для больших файлов лучше позволить SDK выполнить кодирование автоматически):

Ссылки YouTube (нативный формат Gemini)

Ссылки YouTube не требуют загрузки и не подпадают под лимит 20 MB, но их можно передавать только через нативный формат Gemini (google-genai SDK, эндпоинт https://api.apiyi.com).
Для использования нативного формата в других сценариях (потоковая передача, budget рассуждений, вызов функций и т. д.) см. Нативный формат Gemini.

Продвинутые советы

Ссылка на временную метку

Модель по умолчанию делает выборку с частотой 1 кадр в секунду и понимает аудиодорожку, поэтому вы можете ссылаться на моменты напрямую с помощью MM:SS в вашем prompt — это чисто приём составления prompt и работает с любым способом ввода:

Идеи prompt для типовых задач

Один и тот же video поддерживает разные варианты анализа, если просто изменить prompt — никаких изменений кода не требуется:
  • Краткое содержание: кратко изложите тему, ключевые моменты и вывод в 3–5 предложениях
  • Образовательный анализ: выделите ключевые concepts, разбивку по главам и важные timestamps
  • Анализ наблюдения: определите необычное поведение, присутствующих людей/объекты и когда они появляются
  • Маркетинговый обзор: проанализируйте, как представлены преимущества, темп подачи и соответствие целевой аудитории
  • Анализ действий: разберите шаги, детали позы и моменты, которые можно улучшить

Технические примечания

  • Частота выборки: по умолчанию модель выбирает 1 кадр в секунду (FPS) и также понимает аудиодорожку.
  • Использование token: примерно 300 token/секунду при разрешении по умолчанию, примерно 100 token/секунду при низком разрешении — более длинные видео расходуют больше token, поэтому оценивайте это соответствующим образом.
  • Поддерживаемые форматы: mp4, mpeg, mov (quicktime), avi, webm, wmv, 3gpp и другие распространенные форматы.

FAQ

Понимание видео Google не принимает произвольные публичные прямые ссылки (например, https://example.com/video.mp4) и возвращает Request contains an invalid argument. Это не блокировка со стороны APIYI или Nginx. Используйте либо: ① встроенный Base64 (≤20 MB); либо ② ссылку YouTube (нативный формат).
При встроенном Base64 весь тело запроса всегда было ограничено 20 MB (что соответствует официальному лимиту Google). Если то, что «раньше работало», было публичной прямой ссылкой, это никогда не было поддерживаемым способом — просто в некоторых случаях ошибка не возникала; теперь это отклоняется согласно спецификации.
Нет. Официальный Files API Google (client.files.upload()) не поддерживается сторонними сервисами — его поддерживает только собственный эндпоинт Google. Для больших видео используйте ссылку YouTube или сожмите файл до менее чем 20 MB и используйте Base64.
Два пути: ① загрузить в YouTube и передать ссылку (нативный формат, на который не распространяется лимит 20 MB); ② использовать инструмент вроде ffmpeg, чтобы локально сжать или обрезать ключевой фрагмент до менее чем 20 MB, а затем закодировать в base64.

Связанные материалы

Модели и тарифы

Просмотрите все модели Gemini и актуальные тарифы

Нативный формат Gemini

Ссылки YouTube, потоковая передача, бюджет на рассуждение и другие варианты нативного использования

API для понимания изображений

Распознавание содержимого изображений и мультимодальный анализ

Справочник API

Полная спецификация API и сведения об эндпоинтах