> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Gemini AI API guide - Ace Data Cloud

У цій статті буде представлено інструкцію з інтеграції Gemini Videos Generation API, який може генерувати відео Google Gemini (omni-flash) шляхом введення текстових підказок (а також необов'язкових референсних зображень).

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

Щоб використовувати Gemini Videos Generation API, спочатку отримайте ваш API Token у [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) і збережіть його для подальшого використання.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку.

**Один API Token дозволяє викликати всі сервіси платформи, не потрібно подавати заявку окремо для кожного сервісу.** Під час першого отримання надається безкоштовний ліміт, який можна використати для безкоштовного тестування; коли ліміту недостатньо, ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin).

> 📘 Повна документація: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

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

Спочатку розглянемо базовий спосіб використання: введіть підказку `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», щоб провести тестування; отриманий результат буде приблизно таким:

```json theme={null}
{
  "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 такий:

```shell theme={null}
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 такий:

```python theme={null}
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`, щоб спрямувати генерацію відео:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

Потім використовуйте цей `task_id` як `id` для опитування [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks). Після завершення завдання можна отримати нове згенероване відео (це фактичний результат повернення для цього прикладу):

```json theme={null}
{
  "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`, інакше буде повернуто таку помилку параметрів:

```json theme={null}
{
  "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 на цю адресу:

```json theme={null}
{
  "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"
}
```

Одразу повертається такий результат:

```json theme={null}
{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

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

Якщо використано асинхронний зворотний виклик або ви бажаєте самостійно перевірити стан завдання, через [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks) (`POST https://api.acedata.cloud/gemini/tasks`) можна запитати найновіший стан і результат завдання за `task_id`. У тілі запиту передайте `task_id`, повернений під час створення відео, як `id`:

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

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

```json theme={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`: внутрішня помилка сервера або збій генерації на стороні постачальника.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.