Перейти к основному содержанию
В этой статье будет представлено описание интеграции Gemini Videos Generation API, который может генерировать видео Google Gemini (omni-flash) посредством ввода текстового промпта (а также необязательного референсного изображения).

Процесс получения доступа

Чтобы использовать Gemini Videos Generation API, сначала получите ваш API Token в консоли Ace Data Cloud и сохраните его для дальнейшего использования. Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти; после завершения вы автоматически вернётесь на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, не нужно подавать отдельную заявку для каждого сервиса. При первом получении предоставляются бесплатные кредиты для бесплатного тестирования; при недостатке кредитов можно пополнить общий баланс в консоли.
📘 Полная документация: Gemini Videos Generation API →

Базовое использование

Сначала ознакомимся с базовым способом использования: введите промпт prompt, модель model и соотношение сторон aspect_ratio, после чего можно сгенерировать соответствующее видео. Здесь можно увидеть, что мы настроили Request Headers, включая:
  • accept: формат результата ответа, который вы хотите получить; здесь указывается application/json, то есть формат JSON.
  • authorization: ключ для вызова API, после получения его можно выбрать непосредственно из выпадающего списка.
Также настроен Request Body, включающий:
  • prompt: текстовый промпт, описывающий содержимое видео, которое вы хотите сгенерировать, обязателен.
  • model: модель для генерации видео; в настоящее время поддерживается только omni-flash, по умолчанию также omni-flash.
  • aspect_ratio: соотношение сторон генерируемого видео; доступно 16:9 (горизонтальный формат) или 9:16 (вертикальный формат), по умолчанию 16:9.
  • resolution: необязательное выходное разрешение; доступно 720p или 1080p, по умолчанию 720p.
  • image_urls: необязательный массив ссылок на референсные изображения, используемый для направления генерации видео; пустые элементы будут проигнорированы. При использовании video_urls для редактирования видео этот параметр обязателен (как минимум одно изображение).
  • video_urls: необязательный массив ссылок на референсные видео (не более 1), используемый для редактирования видео / видео-референса; при предоставлении необходимо одновременно предоставить как минимум одно image_urls.
  • callback_url: адрес асинхронного обратного вызова; после настройки API немедленно вернёт task_id, а после завершения задачи отправит результат POST-запросом на этот адрес.
  • async: необязательный параметр; при установке в true интерфейс немедленно возвращает task_id, при этом не требуется предоставлять callback_url, затем результат получается путём опроса соответствующего интерфейса запроса задачи.
Нажмите кнопку «Try» для тестирования, полученный результат будет примерно следующим:
Возвращаемый результат содержит несколько полей, описание которых приведено ниже:
  • success: успешно ли выполнен этот запрос на генерацию видео.
  • task_id: ID этой задачи генерации видео.
  • trace_id: ID отслеживания этого запроса, используемый для диагностики проблем.
  • data: список результатов сгенерированных видео.
    • id: уникальный идентификатор сгенерированного видео.
    • video_url: ссылка на сгенерированное видео (null, когда state имеет значение pending).
    • state: статус задачи генерации видео; доступны pending / succeeded / failed.
    • aspect_ratio: соотношение сторон этого видео, соответствует параметру запроса.
    • prompt: промпт, использованный для генерации этого видео.
При синхронном возврате на верхнем уровне также будут добавлены такие поля, как started_at, finished_at, elapsed (затраченное время, секунды) и cost (списание за этот запрос, единица измерения Credit). Нам нужно только получить сгенерированное видео по ссылке video_url из data результата. Соответствующий код CURL приведён ниже:
Соответствующий код Python приведён ниже:

Генерация видео по изображению

Если вы хотите сгенерировать видео на основе референсных изображений, можно передать одну или несколько ссылок на изображения в image_urls, чтобы направлять генерацию видео:

Редактирование видео / эталонное видео (входное видео, генерируемое видео)

Поддерживается прямой сценарий «ввести видео и сгенерировать новое видео»: передайте ссылку на эталонное видео (не более 1) в video_urls и одновременно укажите хотя бы одно эталонное изображение в image_urls, затем опишите желаемый эффект редактирования в prompt (изменение стиля, замена сцены, добавление или удаление элементов и т. д.). Ниже приведён полный реальный пример: видео солнечного пляжа преобразуется в зимнюю сцену с сильным снегопадом, при этом сохраняется расположение пляжа, пальм и лодки. Редактирование видео занимает длительное время (в этом примере около 6,5 минут), поэтому задача отправляется асинхронно через async: true:
После отправки интерфейс немедленно возвращает task_id:
Затем используйте этот task_id в качестве id для опроса Gemini Tasks API. После завершения задачи можно получить новое сгенерированное видео (это фактический результат, возвращённый в данном примере):
Для получения результата с более высоким разрешением установите resolution в значение 1080p (остальные параметры не изменяются).
Подсказка: ссылки на входные/выходные медиафайлы в примерах являются реальными результатами генерации. Срок хранения ссылок на видео и изображения, сгенерированные платформой, ограничен; после истечения срока они станут недействительными. После получения результата своевременно скачайте и сохраните его в собственном хранилище.
Внимание: можно указать не более 1 референсного видео; при указании video_urls необходимо предоставить хотя бы одно изображение image_urls, иначе будет возвращена следующая ошибка параметров:

Асинхронный callback

Генерация видео требует определённого времени обработки. Если вы не хотите поддерживать длительное соединение в ожидании, можно передать callback_url, в этом случае API немедленно вернёт task_id, а после завершения задачи отправит окончательный результат методом POST на этот адрес:
Немедленно возвращаемый результат выглядит следующим образом:

Запрос результата задачи

Если используется асинхронный callback или вы хотите активно запрашивать статус задачи, можно через Gemini Tasks API (POST https://api.acedata.cloud/gemini/tasks) запросить актуальный статус и результат задачи по task_id. В теле запроса передайте task_id, возвращённый при создании видео, в качестве id:
Результат, возвращаемый после завершения задачи, аналогичен следующему: структура response.data совпадает со структурой при синхронной генерации (во время генерации state имеет значение pending, а video_url — null):

Обработка ошибок

Если при выполнении запроса возникает проблема, API возвращает соответствующий код ошибки и описание. Распространённые ошибки:
  • 400: неверные параметры запроса, например отсутствует prompt или недопустимо значение aspect_ratio.
  • 401: ошибка аутентификации: токен недействителен или не соответствует API.
  • 403: недостаточно средств либо запрос отклонён из-за прохождения проверки содержимого.
  • 500: ошибка сервиса или сбой генерации.