Перейти к основному содержанию
Несколько семейств моделей на APIYI умеют «смотреть» видео: с помощью одного prompt модель распознает сцены, действия и текст на экране, а также может ссылаться на ключевые моменты по таймкодам. Помимо Gemini, все семейство Seed (Doubao), модели vision и omni от Qwen, а также Kimi K3 успешно прошли наши тесты. На этой странице приведены список поддерживаемых моделей, универсальный формат запроса и ограничения, о которые часто спотыкаются.
Сначала ознакомьтесь с этими тремя пунктами:
  1. Универсальный формат — video_url: {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,..."}} работает с Seed, Qwen, Kimi, MiniMax и Gemini. Более старый формат image_url + data:video/mp4, описанный в ранних версиях этой страницы, работает только с Gemini — все остальные модели возвращают 400.
  2. GPT, Grok, Claude, GLM и DeepSeek не принимают видео на вход. GPT и GLM незаметно отбрасывают видео и все равно возвращают 200, причем GPT может даже выдумать правдоподобный ответ — см. раздел «Модели, не поддерживающие видео».
  3. Gemini не принимает обычные публичные URL видео: модель может вернуть Request contains an invalid argument либо вернуть 200 с незаметно отброшенным видео (prompt_tokens составляет всего несколько десятков) и ответить, что не видит видео, или даже описать его как черный экран; Seed, Qwen и Kimi могут принимать публичный https URL напрямую.

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

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

Доверьте интеграцию ИИ-агенту

Скопируйте этот prompt и вставьте его в Codex / Claude Code / Cursor

Сначала он загрузит текстовую версию этой страницы (добавьте .md к любому URL документации), а затем напишет код под стек вашего проекта: универсальный формат video_url, ограничение Gemini на отсутствие публичных URL и лимит в 20 МБ, а также проверка prompt_tokens, подтверждающая, что видео действительно дошло до модели, уже заложены в требования.

Интегрируйте или отладьте понимание видео в этом проекте: отправьте видео мультимодальной модели для саммари, описания сцен, анализа действий или привязки к таймкодам.

Изучите документацию перед тем, как писать код: загрузите https://docs.apiyi.com/en/api-capabilities/video-understanding.md для получения текстовой версии этой страницы. Для ссылок на YouTube также изучите страницу gemini/native с …

  1. Эндпоинт и формат: используйте совместимый с OpenAI POST https://api.apiyi.com/v1/chat/completions и всегда передавайте видео как …

Всего 9 требований. Используйте кнопку ниже, чтобы скопировать prompt целиком.

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

Эти результаты получены в ходе тестов, проведенных 2026-10-11 (UTC+8): один и тот же 10-секундный тестовый ролик (разные цифра и фигура каждые 2,5 секунды) отправлялся в каждую модель, которая должна была перечислить цифры по порядку с их временными метками. В качестве контроля использовалось пустое изображение, чтобы исключить ответы, сгенерированные без фактического просмотра видео. Предыдущие gemini-3.7-flash и gemini-3.5-flash, а также проверенная классика gemini-2.5-pro (контекст 2M) и gemini-2.5-flash по-прежнему доступны; 3.8 Flash в нашем тесте израсходовала ровно столько же video tokens, сколько 3.5 Flash (около 713 за 10 секунд), при цене за входные данные в два раза ниже. Показатели задержки и tokens применимы к 10-секундному тестовому клипу 540p, описанному выше; для более длинных видео или видео с более высоким разрешением значения масштабируются примерно пропорционально. Фактическая задержка также зависит от эндпоинта и очередей на стороне провайдера, поэтому для одного и того же клипа время может различаться в 2–3 раза.
Цены на модели синхронизированы с официальными сайтами и могут изменяться вслед за ними; таблица выше приведена только для справки — актуальные данные представлены на вкладке Цены на модели в верхнем меню навигации: Цены на модели.

Модели, не поддерживающие видео

GPT может выдумать ответ после отбрасывания видео: в наших тестах gpt-6-sol выдумала последовательности цифр, которых не было на видео, во всех 3 запусках из 3, а лондонскую улицу описала как «бассейн с надувными кругами». Если вам необходимо использовать эти модели, переключитесь на описанный ниже подход «кадры как изображения».

Способы передачи видео

Ограничение Gemini в 20 МБ: при использовании Base64 общий размер тела запроса (включая закодированное видео) не должен превышать 20 МБ. Для более крупных видео вы можете: ① использовать ссылку на YouTube, ② локально сжать или обрезать видео до размера менее 20 МБ перед кодированием, либо ③ переключиться на Seed / Qwen и передавать публичный URL напрямую.
Провайдер должен иметь доступ к вашему URL: видео скачивается провайдером модели, поэтому адрес должен быть доступен с его стороны. В ходе нашего тестирования URL из объектного хранилища Volcengine успешно работал с Seed, Qwen, Kimi и MiniMax, тогда как URL из Google Cloud Storage возвращал ошибку 403 на Seed. Если вы не уверены, сначала настройте передачу через Base64, а затем переходите на URL.

Быстрый старт: универсальный формат (video_url)

Работает с Seed, Qwen, Kimi, MiniMax и Gemini.
Эквивалентный вызов curl (замените <BASE64_VIDEO> на строку base64 видео или замените весь url на публичный адрес):
Seed позволяет настраивать частоту дискретизации: добавьте "fps": 2 внутри video_url, чтобы более детально рассмотреть быстрое движение (в нашем тесте 10-секундный ролик увеличился с примерно 4 900 до примерно 6 200 входных tokens). Qwen и Kimi игнорируют это поле.

Форматы, специфичные для Gemini

Встроенный base64 (устаревшая форма image_url)

Gemini принимает как форму video_url выше, так и форму image_url ниже, поэтому существующий код продолжит работать; для нового кода используйте video_url, чтобы иметь возможность свободно переключать модели.

Встроенный base64 (нативный формат Gemini)

Если в вашем проекте уже используется официальный SDK google-genai от Google, переходить на совместимый с OpenAI формат нет необходимости: направьте base_url на https://api.apiyi.com и встройте видео с помощью Part.from_bytes. Как и выше, общий размер тела запроса должен быть менее 20 МБ.
Эквивалент для REST: строка base64 очень длинная, поэтому не вставляйте её в аргумент командной строки — сначала запишите её в файл JSON и отправьте с помощью -d @req.json.
Нативный формат упрощает проверку того, что видео дошло до модели: usageMetadata.promptTokensDetails в ответе разделяет входные данные по модальностям — наш 10-секундный тестовый ролик вернулся как VIDEO 660 плюс несколько TEXT tokens, столько же в сумме, сколько и в совместимом с OpenAI формате. Если запись VIDEO отсутствует, значит, видео не было получено.

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

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

Модели без поддержки видео: кадры как изображения

Для моделей, работающих только с изображениями, таких как GPT и Grok, извлекайте кадры локально с фиксированным интервалом и отправляйте их как несколько изображений. В наших тестах gpt-6-sol, gpt-6-luna, gpt-5.6-terra, grok-4.7 и grok-4.5 корректно описали содержание и последовательность по 4 кадрам. Компромисс: звук и движение между кадрами теряются, и вам нужно самостоятельно указывать тайминг в prompt.

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

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

Ссылайтесь на фрагменты напрямую в prompt с помощью MM:SS — это исключительно техника составления prompt, которая работает с любой моделью, поддерживающей видео:
Когда важны точные временные метки, отдавайте предпочтение Seed или Qwen; временные метки MiniMax-M3 в наших тестах оказались ненадежными.

Две причины, по которым ответ может быть недостоверным

① Видео так и не дошло до модели: проверьте usage.prompt_tokens в ответе. 10-секундный ролик занимает около 5 000 tokens в Seed / Qwen и около 700 в Gemini; если там всего несколько десятков tokens, видео было пропущено (именно это происходит в GPT и GLM, а также в Gemini при передаче публичного URL), и такому ответу доверять нельзя. Модель не обязательно сообщит, что ничего не видит: при передаче публичного URL Gemini описывает отсутствующее видео как «полностью черный экран», а GPT придумывает контент, которого там нет. ② Входные данные некорректны, а prompt предполагает наличие контента: например, был отправлен не тот файл, видео декодировалось в черный или серый экран либо во время интеграции использовалось изображение-заглушка. В этом случае prompt_tokens выглядит абсолютно нормально, поэтому подсчет tokens проблему не выявит.
Модели Gemini склонны поддакивать вопросу и выдумывать ответ в случае ②. В наших тестах мы заменили видео пустым изображением:
  • При нейтральном вопросе («опишите, что вы получили») Gemini 3.8 Flash / 3.5 Flash / 3.1 Pro / 3.1 Flash Lite во всех 12 запусках корректно ответили, что это пустое изображение — само понимание изображений у них работает отлично;
  • Но как только вопрос предполагал наличие контента («какие цифры появляются на видео, по порядку» или даже «есть ли какие-либо цифры? если нет, скажите нет»), 3.5 Flash / 3.1 Pro / 3.1 Flash Lite придумали несуществующие цифры в 12 из 18 запусков;
  • Более новая gemini-3.8-flash справляется заметно лучше, но проблема не решена полностью: она все равно придумала ответ в 2 из 7 запусков с теми же наводящими вопросами;
  • При тех же вопросах Seed, Qwen и Kimi корректно ответили, что ничего не видят / цифр нет.
Распознавание реальных видео от этого не страдает. Для пакетных пайплайнов, где вы не контролируете входные данные, сначала задайте нейтральный вопрос, чтобы модель описала то, что видит, убедитесь в корректности входных данных и только затем задавайте конкретный вопрос — либо используйте Seed / Qwen.

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

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

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

  • Gemini: по умолчанию сэмплирует с частотой 1 кадр в секунду и также обрабатывает аудиодорожку; Gemini 3.x по умолчанию рассчитывает кадры в низком разрешении, что в наших тестах составило около 70 tokens в секунду.
  • Seed / Qwen: около 500 tokens в секунду в наших тестах (видео 540p); сэмплирование Seed можно настроить с помощью fps.
  • Kimi K3: около 1 400 tokens в секунду в наших тестах, поэтому длинные видео обходятся заметно дороже.
  • Поддерживаемые форматы: распространенные форматы, такие как mp4, mov и webm; конвертация в H.264 mp4 обеспечивает наилучшую совместимость.

Часто задаваемые вопросы

Нет. Claude и Grok сразу возвращают ошибку; эндпоинт чата GPT молча отбрасывает видео и всё равно возвращает 200, при этом модель может выдумать ответ. Если вам нужны именно эти модели, сначала извлеките кадры и отправьте их как изображения — см. раздел «Модели без поддержки видео: кадры как изображения».
Прошли наши тесты: всё семейство Seed (seed-2-0-pro-260328, dola-seed-2-1-turbo-260628, seed-2-0-lite-260428, seed-2-0-mini-260428, seed-1-8-251228), модели Qwen qwen3.8-max, qwen3.8-flash, qwen3-vl-plus и qwen3.5-omni-plus, а также kimi-k3. MiniMax-M3 распознаёт содержимое, но ошибается во временных метках. glm-5.3 и deepseek-v4-flash-vision-exp не поддерживают видео.
Вероятнее всего, вы используете устаревший формат image_url + data:video/mp4, который принимает только Gemini. Переключитесь на {"type": "video_url", "video_url": {"url": ...}}, и он будет работать со всеми провайдерами.
Сначала убедитесь, что с входными данными всё в порядке (нет чёрного экрана, пустого кадра или неподходящего файла). В наших тестах, если входные данные были некорректными, а вопрос предполагал наличие содержимого, Gemini была склонна выдумывать ответ под вопрос. Для диагностики переключитесь на нейтральный prompt вроде «describe what you received» и проверьте, описывает ли он ваше видео; см. раздел «Два признака недостоверного ответа».
Gemini не принимает произвольные публичные URL (например, https://example.com/video.mp4); это не блокировка со стороны APIYI. Для Gemini используйте встроенный base64 (до 20 МБ) или ссылку на YouTube либо переключитесь на Seed / Qwen, которые умеют загружать публичные URL напрямую. В /v1/chat/completions ошибка возникает не всегда: может вернуться 200 с утверждением модели, что она видит чёрный экран — в этом случае prompt_tokens составляет всего несколько десятков, и результат непригоден для использования.
При передаче через встроенный base64 Gemini всегда ограничивала общий размер тела запроса 20 МБ (в соответствии с официальным лимитом Google). Если то, что «раньше работало», было публичным URL, этот способ никогда официально не поддерживался — в ряде случаев он просто случайно не вызывал ошибку, а теперь отклоняется явно.
Нет. Официальный Files API от Gemini (client.files.upload()) не поддерживается на сторонних эндпоинтах — только на собственных серверах Google. Для больших видео используйте ссылку на YouTube, сжимайте видео до 20 МБ для передачи в base64 или переходите на Seed / Qwen с публичным URL.
Три варианта: ① загрузить на YouTube и передать ссылку (нативный формат Gemini); ② с помощью ffmpeg или аналогичного инструмента сжать видео либо обрезать ключевой фрагмент до размера менее 20 МБ, после чего закодировать его в base64; ③ разместить видео в публично доступном объектном хранилище и передать URL моделям Seed / Qwen.

Связанные ресурсы

Цены на модели

Все модели и актуальные цены

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

Ссылки на YouTube, потоковая передача, thinking budget и другие нативные возможности

API распознавания изображений

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

Qwen3.8-Max

Флагман Qwen с нативным вводом изображений и видео