Сначала прочитайте это: видео можно передать только через 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 по-прежнему доступны. См. Модели и тарификация для полной информации о тарификации.
Методы ввода видео
Именно здесь возникает большинство проблем. Проверьте таблицу ниже, чтобы убедиться, что ваш метод ввода поддерживается:Быстрый старт: встроенный Base64 (формат, совместимый с OpenAI)
Самый распространенный подход: прочитайте локальное видео → закодируйте его в base64 → передайте его в полеimage_url.
<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 (нативный формат).Почему лимит 20 MB? Раньше это работало
Почему лимит 20 MB? Раньше это работало
При встроенном Base64 весь тело запроса всегда было ограничено 20 MB (что соответствует официальному лимиту Google). Если то, что «раньше работало», было публичной прямой ссылкой, это никогда не было поддерживаемым способом — просто в некоторых случаях ошибка не возникала; теперь это отклоняется согласно спецификации.
Могу ли я использовать files.upload для загрузки больших видео?
Могу ли я использовать files.upload для загрузки больших видео?
Нет. Официальный Files API Google (
client.files.upload()) не поддерживается сторонними сервисами — его поддерживает только собственный эндпоинт Google. Для больших видео используйте ссылку YouTube или сожмите файл до менее чем 20 MB и используйте Base64.Что насчет видео больше 20 MB?
Что насчет видео больше 20 MB?
Два пути: ① загрузить в YouTube и передать ссылку (нативный формат, на который не распространяется лимит 20 MB); ② использовать инструмент вроде ffmpeg, чтобы локально сжать или обрезать ключевой фрагмент до менее чем 20 MB, а затем закодировать в base64.
Связанные материалы
Модели и тарифы
Просмотрите все модели Gemini и актуальные тарифы
Нативный формат Gemini
Ссылки YouTube, потоковая передача, бюджет на рассуждение и другие варианты нативного использования
API для понимания изображений
Распознавание содержимого изображений и мультимодальный анализ
Справочник API
Полная спецификация API и сведения об эндпоинтах