Перейти к основному содержанию

​
Обзор

VEO 3.1 Official — это канал официального релея APIYI для Google Veo 3.1, обеспечивающий прозрачную пересылку запросов к асинхронным эндпоинтам veo-3.1-generate-preview / veo-3.1-fast-generate-preview в Google AI Studio с идентификаторами моделей, полями ответов и ограничениями, полностью идентичными вышестоящему сервису. Тарификация за каждый запрос, доступность для вызова в группе Default — самый удобный и доступный канал Veo 3.1 официального качества на сегодняшний день.
🎬 Главное: прозрачная пересылка в Google AI Studio + нативный синхронизированный звук + гибкая длительность 4 / 6 / 8 секунд + три варианта разрешения (720p / 1080p / 4k) + тарификация за запрос от $0.3 + группа Default + Pay-per-request или Pay-as-you-go Priority tokens (выделенная группа не требуется; чистый Pay-as-you-go не поддерживается). Подходит для коротких рекламных роликов, материалов для e-commerce, контента для социальных сетей и демонстраций продуктов, где требуется официальное качество при максимально простом подключении.
⚠️ Скачивайте через /content и сохраняйте у себя: как только status: "completed", вызовите GET /v1/videos/{task_id}/content для получения бинарных данных MP4 и сохраните их в собственном OSS / CDN перед отдачей конечным пользователям. Завершенный ответ может также содержать video_url (прямая ссылка без авторизации) — срок ее действия истекает примерно через 24 часа (см. expires_at), и она не гарантируется для каждой задачи, поэтому используйте ее только для временного предпросмотра и никогда не используйте как постоянный адрес. См. раздел Эндпоинты API ниже.

API генерации видео по тексту

POST /v1/videos, генерация видео только по тексту — тело запроса в формате JSON, самая простая точка входа.

API генерации видео по изображению

POST /v1/videos + multipart-загрузка input_reference для превращения статичного изображения в видеоролик.

Официальный канал против reverse-канала

Матрица принятия решений в сравнении с существующим VEO 3.1 (reverse-канал).

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

Отлаживайте этот эндпоинт прямо в инструменте визуального тестирования iCover — без написания кода.

Поиск и скачивание асинхронных задач

Просматривайте отправленные задачи генерации видео и скачивайте ссылки на видео в консоли APIYI — отдельная точка доступа к задачам без использования API.

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

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

Сначала он загрузит текстовую версию этой страницы (добавьте .md к любому URL документации), а затем напишет код под стек вашего проекта — асинхронный опрос (polling), необходимость самостоятельно скачивать MP4, ступенчатые таймауты и жесткие ограничения для 4K уже заложены в требования.

Выполните интеграцию / устранение неполадок VEO 3.1 Official text-to-video и image-to-video в этом проекте.

Ознакомьтесь с документацией перед изменением кода: загрузите https://docs.apiyi.com/en/api-capabilities/veo-3-1-official/overview.md для получения текстовой версии этой страницы. Для более подробной информации по параметрам добавьте .md к …

  1. Используйте трехэтапный асинхронный процесс, а не синхронное ожидание. Этот канал работает только асинхронно: POST /v1/videos отправляет задачу и возвращает task_id, затем опрашивайте …

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

​
Почему официальный VEO 3.1 от APIYI?

Полная замена официального канала Google / Vertex AI, оптимизированная для production-сценариев с точки зрения онбординга, стабильности и стоимости:

Официальный passthrough · Идентичные Model IDs

Прозрачный passthrough к асинхронным эндпоинтам Veo 3.1 в Google AI Studio. Model IDs (veo-3.1-generate-preview / veo-3.1-fast-generate-preview) в точности совпадают с upstream, с полным соответствием полей и ограничений запросов и ответов.

Беспроблемный онбординг · Без переключения группы

Вызовы работают в Default группе с Pay-per-request или Pay-as-you-go Priority Tokens (чистый Pay-as-you-go не поддерживается). Отдельное переключение группы не требуется; существующие Pay-per-request Tokens работают как есть — самый беспроблемный официальный канал для Veo 3.1.

Неограниченные параллельные запросы · Production-масштаб

Агрегированный пул аккаунтов с прозрачным proxy — масштабируйте batch-съёмки, рекламные пайплайны и высоконагруженное production-производство линейно. Нет потолка тарифа Google на аккаунт.

Тарификация за запрос · Более чем на 60% дешевле, чем Google

veo-3.1-fast-generate-preview $0.3/req, veo-3.1-generate-preview $1.2/req — единая для 4/6/8 сек и 720p/1080p/4k. По сравнению с официальным 8s 1080p Google, экономия 62–68%, используйте бонусы за пополнение для дополнительной экономии; неудачные задачи не тарифицируются.

Глобальный доступ без трения

Не требуется зарубежный сервер или proxy — подключайтесь к api.apiyi.com напрямую из дата-центров Mainland China, residential-сетей или зарубежных узлов. Полностью обойдитесь без трансграничной настройки Google AI Studio / Vertex AI.

Профессиональная поддержка · Корпоративное внедрение

Наша команда глубоко разбирается в генерации видео: prompt engineering, подборе разрешения, пакетном производстве и постобработке. Полная техническая поддержка от PoC до production для корпоративных клиентов.

​
Ключевые возможности

Нативное синхронизированное аудио

Veo 3.1 изначально выводит видео с синхронизированным аудио (фоновые звуки, диалоги, музыка). Отдельная постобработка аудио не нужна — опишите желаемое аудио в вашем prompt.

Гибкая длительность 4 / 6 / 8 секунд

seconds строковый enum: "4" / "6" / "8". Тарификация за каждый запрос, длительность не влияет на цену. Уровни 1080p / 4k требуют "8".

Три уровня разрешения

720p / 1080p / 4k, единая тарификация за запрос. Свободно переключайте альбомную ориентацию (16:9) и портретную (9:16).

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

Veo 3.1 лидирует в своем классе по движению камеры, физике объектов и точности выражения персонажей. Широкая поддержка ключевых слов языка камеры (push/pull/pan/dolly, низкие/высокие ракурсы).

Изображение в видео (input_reference)

Загрузите одно изображение как визуальную опору для анимации статичного контента. См. Изображение в видео.

Асинхронная модель задач

При отправке сразу возвращается task_id. Отдельно опрашивайте статус и скачивайте итоговое видео — это идеально подходит для пакетного управления и сценариев возобновления после сбоя.

Протокол, совместимый с OpenAI

Аутентификация base_url=https://api.apiyi.com/v1 + Bearer. Работает через raw HTTP или низкоуровневый client.post() OpenAI SDK.

Сбойные запросы бесплатны

В асинхронном режиме неудачные генерации, отклонения по политике контента и ошибки параметров не тарифицируются. Оплачиваются только задачи status=completed.

​
Цены

APIYI использует тарификацию pay-per-request — фиксированная цена в пределах поддерживаемых комбинаций длительности/разрешения, без доплаты за более длинный вывод или более высокое разрешение. По публичным тарифам ai.google.dev/gemini-api/docs/pricing, официальный Veo 3.1 от Google тарифицируется за секунду; указанные ниже скидки рассчитаны для 8-секундных видео.
Примечания по тарификации:
  • Взимается за запрос по названию модели, независимо от длительности (4/6/8 сек), разрешения (720p/1080p/4k) или наличия input_reference — выбор 4K стоит столько же, сколько 720p
  • В асинхронном режиме неудачные генерации / отклонения по политике контента / ошибки емкости не тарифицируются
  • Тарифные уровни бонуса при пополнении в Top-Up Promotions дополнительно снижают эффективную стоимость
  • Рендеринг 4K работает в 4–6 раз медленнее и создает файлы примерно в 10 раз больше — для ежедневного использования по умолчанию выбирайте 1080p
  • Официальный тариф Google для 4K составляет $0.30/сек (fast) / $0.60/сек (standard), то есть $2.40 / $4.80 за 8 сек (источник: ai.google.dev/gemini-api/docs/pricing)

​
Настройка группы

VEO 3.1 Official работает в группе Default (1x), отдельное переключение группы не требуется. Режим тарификации Token должен быть Pay-per-request или Pay-as-you-go Priority — чистый Pay-as-you-go не поддерживается (при необходимости переключите режим Token в консоли).
Низкий порог входа: VEO 3.1 Official работает в группе Default и поддерживает как Pay-per-request, так и Pay-as-you-go Priority, без необходимости настраивать отдельную группу — идеально, если вы хотите “подключить существующий Pay-per-request Token + изменить base_url” для онбординга без настройки.

​
Технические характеристики

При разрешении 1080p / 4k параметр seconds должен иметь значение "8" — "4" или "6" будут отклонены вышестоящим сервисом. Для 720p поддерживаются все три варианта длительности.

​
Эндпоинты API

⚠️ Скачивайте через /content; video_url предназначен только для временного предпросмотраСтандартный способ получения видео — GET /v1/videos/{task_id}/content, который возвращает бинарный поток MP4 (требуется заголовок Authorization: Bearer).Что следует учитывать:
  • Ответ о завершении задачи может содержать video_url (прямая ссылка без авторизации) и expires_at (примерно через 24 часа); это не гарантируется для каждой задачи, поэтому ваш код должен обрабатывать его отсутствие
  • Фронтенд не может использовать эндпоинт /content напрямую в теге <video> — запросы браузера без заголовка авторизации вернут ошибку 401; video_url можно использовать для временного предпросмотра до истечения срока действия
  • Как только status: "completed", скачайте MP4 и сохраните его в собственном хранилище OSS / CDN, а затем отдавайте свой URL конечным пользователям
  • Удаленная копия хранится около 24 часов — не полагайтесь в долгосрочной перспективе на удаленные task_id или video_url для получения видео
Выбор эндпоинта: основной — api.apiyi.com; резервный шлюз b.apiyi.com работает аналогично.

​
Key Parameters

⚡ Полная справка по параметрам: перейдите к Text-to-Video - Parameter Reference за полной таблицей, охватывающей типы model / prompt / seconds / size / metadata.*, значения по умолчанию и ограничения. В этом разделе разбираются только 3 наиболее проблемных параметра.

​
seconds (длительность видео)

Поле длительности называется seconds (а не duration) и должно быть строкой ("4" / "6" / "8"). Если передать число, возвращается:
Распространенная ошибка: поле с именем duration тихо игнорируется. duration не распознается этим каналом → оно отбрасывается → длительность откатывается к значению по умолчанию 4 сек.:
  • В 720p (и на других уровнях, где разрешены 4 сек.): ошибки нет, но вы получаете только 4 сек. (это именно тот случай «отправили 8s, получили 4s»)
  • В 1080p / 4k: 4 сек. недопустимы, поэтому возникает ошибка Resolution 1080p requires duration seconds to be 8 seconds, but got 4
Правильное использование: отправляйте поле seconds со значением "8" (строка).
Приоритет параметров: metadata.durationSeconds > seconds > 8

​
metadata.resolution (уровень разрешения)

Приоритет параметров: metadata.resolution > size > 720p

​
⚠️ Не передавайте generateAudio

Veo 3 / 3.1 изначально поддерживает звук, но параметр generateAudio передавать нельзя — вышестоящий сервис отклонит запрос с INVALID_ARGUMENT. Чтобы управлять звуком, запишите намерение в свой prompt:
“Морской маяк в сумерках; волны, далекие морские птицы, тихий ветер, кинематографическая атмосфера”

​
Рекомендации

1

Выбирайте модель под задачу

  • Итерации / пакетный предпросмотр → veo-3.1-fast-generate-preview ($0.3/запрос)
  • Финальная сдача / 4K → veo-3.1-generate-preview ($1.2/запрос)
  • Запустите обе с одинаковым prompt + seed; выберите визуально
2

Сначала проверяйте на 4 секундах

Для каждого нового prompt начинайте с seconds: "4", чтобы проверить движение камеры и стиль (рендер 60–90 сек, $0.3). Переходите на 8 сек или 1080p, как только визуальный стиль утвержден.
3

Используйте асинхронный поллинг, а не синхронное ожидание

Официальный канал работает только асинхронно: отправьте POST для отправки и получения task_id → опрашивайте GET /v1/videos/{task_id} каждые 8–10 сек до status: "completed" → скачивайте из /content. Без webhook; только поллинг.
4

Задавайте клиентские таймауты по категориям

  • 720p / 1080p: жесткий таймаут 3 мин
  • 4K: жесткий таймаут 10 мин
  • Отправка POST (multipart): минимум 30 сек
5

Скачивайте сразу после завершения

Как только status переключается в completed, немедленно скачивайте файл в собственное хранилище OSS / CDN — удаленная копия хранится всего около 24 часов, поэтому не стоит рассчитывать на долгосрочное хранение по удаленному task_id. Эндпоинт /content иногда возвращает 400 сразу после смены status; повторите попытку через 4 секунды (в примерах клиентов это уже предусмотрено). Ответ 502 от этого же эндпоинта означает, что провайдер не может получить файл — повторные попытки не помогут.
6

Описывайте требования к звуку в prompt

Не передавайте generateAudio (возвращает INVALID_ARGUMENT). Для фоновых шумов, диалогов и фоновой музыки описывайте их в prompt: «waves, distant seabirds, low wind sounds».
7

Ограничивайте частоту запросов на своей стороне

Лимиты на параллельные запросы публично не задокументированы; на практике 10 одновременных отправок успешно встали в очередь. Рекомендуется ограничение на стороне продакшена: активных запросов ≤ 10 с экспоненциальной задержкой для 429 / 5xx.

​
Коды ошибок и повторные попытки

Рекомендуемые настройки клиента:
  • Таймаут отправки POST-запроса: 30 сек (для multipart-загрузок может потребоваться больше)
  • Интервал опроса (polling): 8–10 сек; максимальное время ожидания для 720p/1080p — 3 мин, для 4K — 10 мин
  • Повтор с экспоненциальной задержкой для ошибок 5xx и failed (рекомендуется 1–2 попытки)
  • При ошибке 400 от /content повторяйте запрос каждые 4 секунды в течение примерно до 30 секунд
  • Обрабатывайте 400 и 502 от /content по-разному: ошибка 400 исчезает при повторной попытке; 502 — нет: прекратите попытки после 2 раз, пометьте задачу как завершившуюся с ошибкой и сохраните task_id

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

Официальный (эта страница): прозрачный проброс к апстрим-эндпоинтам Google AI Studio. Идентификаторы моделей совпадают с апстримом Google (veo-3.1-generate-preview / veo-3.1-fast-generate-preview), стоимость — $0.3 / $1.2 за запрос, только асинхронный эндпоинт.Reverse (существующий VEO 3.1): доступ через реверс-инжиниринг к Google Flow. Идентификаторы моделей — серии veo-3.1-fast / veo-3.1 / -fl, стоимость от $0.15 за запрос — дешевле, поддерживаются как потоковый синхронный (streaming sync), так и асинхронный режимы, плюс frame-to-video (первый/последний кадр).Полную информацию см. в Матрице выбора: Official или Reverse. Оба канала сосуществуют; выбирайте в зависимости от задач бизнеса.
Поле запроса — seconds (строка "4" / "6" / "8"). Название duration не распознается — оно просто игнорируется, и длительность откатывается к значению по умолчанию в 4 секунды, что и является первопричиной проблемы «отправили 8s, а получили только 4s».Что касается того, почему это должна быть строка: структура Go на бэкенде объявляет это поле (внутреннее имя duration) как string, поэтому число отклоняется на уровне декодера с ошибкой parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string (duration в этой ошибке — внутреннее имя поля на бэкенде, в вашем же запросе по-прежнему передается seconds). Запомните: передавайте seconds и берите значение в кавычки: "4" / "6" / "8".
Veo 3 / 3.1 — это модель генерации видео с нативной поддержкой звука, но параметр generateAudio передавать нельзя (апстрим возвращает INVALID_ARGUMENT). Чтобы управлять звуком, опишите желаемое в вашем prompt:
«Прибрежный маяк в сумерках; волны, далекие чайки, негромкий шум ветра, кинематографичная атмосфера»
  • При одинаковых параметрах время рендеринга примерно одинаково (замеры для 720p 8 сек: fast 83 с, standard 78 с). fast не быстрее — он дешевле ($0.3 против $1.2)
  • По умолчанию используйте veo-3.1-fast-generate-preview
  • Переключайтесь на veo-3.1-generate-preview для финальной сдачи работы или когда критически важны детализация и физическая согласованность
  • A/B-тестирование в продакшене: запустите оба варианта с одинаковым prompt + seed и выберите визуально
В большинстве случаев не рекомендуется:
  • Одинаковая цена за запрос выглядит привлекательно
  • Но рендеринг происходит в 4–6 раз медленнее (720p 80 с → 4K 350 с)
  • Файлы примерно в 10 раз больше (720p 4 МБ → 4K 40 МБ) — расходы на трафик и хранилище удваиваются
  • 1080p визуально достаточно для большинства сценариев воспроизведения
Если вам действительно нужен 4K: используйте veo-3.1-generate-preview, укажите seconds="8" (обязательно), таймаут на клиенте ≥ 10 мин, запускайте как фоновую асинхронную задачу.
  • webhook отсутствуют; выполняйте только опрос GET /v1/videos/{task_id}
  • Рекомендуемый интервал опроса: 8 сек (по замерам этого достаточно, и это не приведет к превышению лимита запросов)
  • Замеренное время: 720p / 1080p — 60–115 сек, 4K — 5–6 мин
  • Таймауты на стороне клиента: 3 мин для 720p/1080p, 10 мин для 4K
400: просто подождите. Сразу после того, как status переключается в completed, вызов /v1/videos/{task_id}/content иногда возвращает 400, так как видеофайл еще не завершил синхронизацию. Это окно длится примерно до 20 секунд, поэтому повторяйте запрос каждые 4 секунды в течение максимум 30 секунд (в примерах клиентов это уже реализовано). При использовании curl обратите внимание, что --retry по умолчанию не повторяет запрос при 400 — добавьте -f --retry-all-errors.502: повторные попытки не помогут. Тело ответа выглядит как {"error":{"message":"Upstream service returned status 502"}}. Сама генерация прошла успешно — GET /v1/videos/{task_id} по-прежнему возвращает status: "completed" со статусом progress: 100, — но провайдер не может получить этот видеофайл. По нашим замерам, ошибка 502 сохраняется и спустя часы, поэтому сама по себе ситуация не исправится. Никогда не делайте бесконечный цикл повторов для этой ошибки.Что делать:
  1. Повторите запрос максимум дважды; если по-прежнему возвращается 502, пометьте задачу как завершившуюся сбоем
  2. Сохраните task_id и свяжитесь с нами — тарификация за эту генерацию уже произошла, мы проверим данные и решим вопрос
  3. Повторная отправка в виде новой задачи обычно успешно создает видео; менять prompt не требуется
Сейчас такое случается редко: большинство задач перед отправкой ответа completed проверяются на наличие доступного для загрузки видеофайла; если файл получить невозможно, задача переходит в статус status: "failed" (с указанием причины в error.message), а списанные средства автоматически возвращаются, поэтому вы больше не платите за видео, которое не можете забрать. Однако полностью исключить это нельзя — возврат GET /v1/videos/{task_id} со значением completed не означает, что видео гарантированно доступно для скачивания. Относитесь к этому как к двум отдельным проверкам успешности.
Иногда, но только временно. Ответ о завершении задачи может содержать video_url (прямая ссылка без авторизации) и expires_at (временная метка примерно через 24 часа после завершения). Это не гарантируется для каждой задачи, и ссылка перестает работать после истечения срока действия, поэтому не распространяйте ее в качестве постоянного адреса.Стандартный способ получения видео: после status: "completed" вызовите GET /v1/videos/{task_id}/content для получения бинарного потока MP4 (требуется заголовок Authorization: Bearer). Это работает для каждой задачи.Стандартный паттерн для продакшена:
  1. Бэкенд скачивает MP4 сразу после завершения задачи → отправляет в ваше собственное хранилище OSS / CDN
  2. Конечным пользователям отдается ваш CDN URL
  3. Тег <video> на фронтенде НЕ должен указывать напрямую на /content — браузеры не могут прикрепить заголовок авторизации, и запросы завершатся с ошибкой 401; при наличии video_url вы можете использовать его для мгновенного предпросмотра
Около 24 часов, согласно полю expires_at в ответе (если поле отсутствует, считайте срок равным 24 часам). Настоятельно рекомендуется скачивать файл сразу после завершения и сохранять локально — не полагайтесь в долгосрочной перспективе на удаленные task_id или video_url; ни один из них не работает после истечения срока.
Поле progress имеет низкую степень детализации — оно переключается только между несколькими фиксированными шагами (такими как 0 / 10 / 30 / 50 / 100). Не используйте его для процентного индикатора прогресса (progress bar). Используйте спиннер или рассчитывайте соотношение «прошедшее время / ожидаемое время» самостоятельно.
Нет. Плата взимается только за задачи в статусе status=completed. Задачи со статусом failed, отмененные, отклоненные политикой контента или завершившиеся ошибкой параметров — бесплатны. Нет готового видео — нет списания.
Не байт-в-байт. Замеры показали: одинаковый prompt + одинаковый seed (88888) + одинаковые параметры при двух запусках fast дают размеры файлов 9.81 МБ и 9.25 МБ, md5 полностью различаются, время рендеринга также разное.Однако seed — это не просто декорация: результаты с одинаковым seed группируются близко друг к другу (тест из 5 запусков показал разброс размера файлов внутри группы всего 6%), тогда как при смене seed происходит систематический сдвиг (межгрупповой разброс +36.8%). Выводы:
  • Нужен «стабильный стиль/вид» → зафиксируйте seed
  • Хотите «исследовать вариации» → меняйте seed вместо бесконечной правки prompt
  • Нужен «точный повтор» → забудьте об этом, просто сохраняйте mp4
На данный момент ничего из этого не поддерживается. Режим Image-to-video принимает только 1 изображение с фиксированным именем поля input_reference, и только в виде файла или base64, удаленные URL не поддерживаются.Апстрим Google Veo 3.1 поддерживает несколько референсов, первый/последний кадры и расширение видео, но данный канал этого не умеет. Для работы с первым/последним кадром используйте серию -fl в VEO 3.1 (Reverse).
При тестировании 10 одновременных отправок все задачи успешно встали в очередь без отклонений. Точный верхний лимит публично не разглашается. Для продакшена рекомендуется ограничение: количество активных запросов в обработке (in-flight) ≤ 10, с экспоненциальной задержкой при ошибках 429 / 5xx.
  • Видимых водяных знаков нет
  • Но видео содержат метаданные Google C2PA Content Credentials (выданные Google C2PA Media Services, формат urn:c2pa:...), встроенные в структуру MP4. Конечные пользователи их не видят; инструменты C2PA (например, Adobe Content Authenticity) могут подтвердить факт «сгенерировано с помощью Veo»
  • Учитывайте это при сценариях дистрибуции; на обычное воспроизведение это никак не влияет
Частично. Интерфейс соответствует соглашениям OpenAI (авторизация через Bearer + /v1/...), но официальный SDK OpenAI не предоставляет метод videos.create (/v1/videos — это кастомный путь). Используйте низкоуровневый метод client.post() из SDK OpenAI или обычные HTTP-запросы. Обычный HTTP проще всего — см. примеры кода в Интерактивной песочнице Text-to-Video.

​
Связанные документы

VEO 3.1 Official — это стабильный сервис APIYI с официальным реле — прозрачный passthrough к Google AI Studio. Идентификаторы моделей, поля ответов и ограничения полностью совпадают с upstream Google, а канал работает в группе Default с тарификацией pay-per-request — это самый бесшовный канал официального качества из доступных. Пожалуйста, отправляйте отзывы на панели поддержки в консоли.