Інструкція з інтеграції 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"
  ]
}

Редагування відео / референсне відео (вхідне відео, згенероване відео)

Підтримується безпосереднє «введення одного відео та генерація нового відео»: передайте одне посилання на референсне відео (максимум 1) у video_urls і одночасно надайте щонайменше одне референсне зображення в 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_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"
}

Запит результату завдання

Якщо використано асинхронний зворотний виклик або ви бажаєте самостійно перевірити стан завдання, через 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: автентифікація не вдалася, токен недійсний або не відповідає API.
403: недостатньо коштів, або запит відхилено через проходження перевірки вмісту.
500: внутрішня помилка сервера або збій генерації на стороні постачальника.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Coding

Інші посібники

Інструкція з інтеграції Gemini Videos Generation API

Процес подання заявки

Базове використання

Генерація відео із зображення

Редагування відео / референсне відео (вхідне відео, згенероване відео)

Асинхронний зворотний виклик

Запит результату завдання

Обробка помилок

​Процес подання заявки

​Базове використання

​Генерація відео із зображення

​Редагування відео / референсне відео (вхідне відео, згенероване відео)

​Асинхронний зворотний виклик

​Запит результату завдання

​Обробка помилок

Процес подання заявки

Базове використання

Генерація відео із зображення

Редагування відео / референсне відео (вхідне відео, згенероване відео)

Асинхронний зворотний виклик

Запит результату завдання

Обробка помилок