Описание интеграции Gemini Videos Generation API

В этой статье будет представлено описание интеграции 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": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Возвращаемый результат содержит несколько полей, описание которых приведено ниже:

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 приведён ниже:

curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'

Соответствующий код Python приведён ниже:

import requests

url = "https://api.acedata.cloud/gemini/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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

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

{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}

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

Поддерживается непосредственный вариант «ввести одно видео, сгенерировать новое видео»: передайте одну ссылку на референсное видео в video_urls (не более 1), и одновременно предоставьте как минимум одно референсное изображение в image_urls (жёсткое требование вышестоящей системы), затем опишите желаемый эффект редактирования через prompt (изменение стиля, смена сцены, добавление или удаление элементов и т. д.). Ниже приведён полный реальный пример — преобразование видео солнечного пляжа в зимнюю сцену с обильным снегопадом с одновременным сохранением расположения пляжа, пальм и лодки. Редактирование видео занимает больше времени (в данном примере около 6,5 минут), поэтому используется асинхронная отправка с async: true:

{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}

После отправки интерфейс немедленно возвращает task_id:

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

Затем используйте этот task_id в качестве id для опроса Gemini Tasks API, после завершения задачи можно получить новое сгенерированное видео (это фактический результат возврата данного примера):

{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Если требуется более высокое разрешение, можно установить resolution в значение 1080p (остальные параметры остаются без изменений).

Подсказка: ссылки на входные / выходные медиафайлы в примере являются реальными результатами генерации. Ссылки на видео и изображения, сгенерированные платформой, имеют срок хранения и станут недействительными после его истечения, поэтому после получения результата своевременно скачайте и сохраните его в собственное хранилище.

Внимание: можно использовать не более 1 референсного видео; при предоставлении video_urls необходимо предоставить как минимум одно image_urls, иначе будет возвращена следующая ошибка параметров:

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}

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

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

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}

Немедленно возвращаемый результат выглядит следующим образом:

{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

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

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

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

Результат, возвращаемый после завершения задачи, аналогичен следующему: структура response.data совпадает со структурой при синхронной генерации (во время генерации state имеет значение pending, а video_url — null):

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}

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

Когда с запросом возникают проблемы, API возвращает соответствующий код ошибки и описание; распространённые случаи следующие:

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

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Описание интеграции Gemini Videos Generation API

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

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

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

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

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

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

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

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

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

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

​Редактирование видео / референсное видео (входное видео, генерируемое видео)

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

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

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

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

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

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

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

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

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

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