> ## 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"
  ]
}
```

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

Поддерживается непосредственный вариант «ввести одно видео, сгенерировать новое видео»: передайте одну ссылку на референсное видео в `video_urls` (не более 1), и **одновременно** предоставьте как минимум одно референсное изображение в `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

Генерация видео требует определённого времени обработки. Если вы не хотите поддерживать длительное соединение в ожидании, можно передать `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"
}
```

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

Если используется асинхронный callback или вы хотите активно запрашивать статус задачи, можно через [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`: ошибка аутентификации, token недействителен или не соответствует API.
* `403`: недостаточно баланса или запрос отклонён проверкой содержимого подсказки.
* `500`: внутренняя ошибка сервера или сбой вышестоящей генерации.


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