> ## 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.

# Grok Videos Generation API інтеграційна інструкція

> Grok API guide - Ace Data Cloud

Цей документ представить інтеграційну інструкцію для Grok Videos Generation API, який може генерувати відео Grok Imagine (xAI) за допомогою текстових підказок, вхідних зображень та необов'язкових референсних зображень.

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

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

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

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

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

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

## Опис моделей

Цей API вибирає верхній кінець через суфікс назви моделі: `:reverse` використовує швидкий/стандартний кінець (дешевше), `:official` використовує офіційний кінець (вища якість, оплата за секунди виходу). Підтримується чотири моделі:

* `grok-imagine-video-1.5-fast:reverse` (за замовчуванням): підтримує відео, згенероване з тексту (тільки передайте `prompt`), та відео, згенероване з зображення (передайте `image_url`), тривалість 6–30 секунд, оплата за тривалістю, найдешевше.
* `grok-imagine-video:reverse`: підтримує відео, згенероване з тексту та зображення, тривалість 1–15 секунд, оплата за секунди виходу.
* `grok-imagine-video:official`: офіційний кінець, підтримує відео, згенероване з тексту та зображення, тривалість 1–15 секунд, оплата за секунди виходу, вища якість.
* `grok-imagine-video-1.5:official`: офіційний кінець, **підтримує тільки відео, згенероване з зображення**, **обов'язково** передайте `image_url`, тривалість 1–15 секунд, підтримує до `1080p`, оплата за секунди виходу.

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

Спочатку ознайомтеся з основним способом використання, введіть підказку `prompt`, модель `model` та інші параметри, щоб згенерувати відповідне відео.

Ми налаштували заголовки запиту, включаючи:

* `accept`: формат відповіді, який ви хочете отримати, тут вказано `application/json`, тобто формат JSON.
* `authorization`: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.

Також налаштовано тіло запиту, включаючи:

* `prompt`: текстова підказка, що описує вміст відео, яке потрібно згенерувати. Обов'язково для відео, згенерованого з тексту; необов'язково при передачі `image_url`.
* `model`: модель для генерації відео, можна вибрати `grok-imagine-video-1.5-fast:reverse` (за замовчуванням), `grok-imagine-video:reverse`, `grok-imagine-video:official` або `grok-imagine-video-1.5:official`.
* `image_url`: посилання на вхідне зображення для відео, згенерованого з зображення. Обов'язково, коли `model` є `grok-imagine-video-1.5:official`.
* `reference_image_urls`: масив необов'язкових посилань на референсні зображення, які використовуються для направлення стилю або вмісту відео.
* `aspect_ratio`: співвідношення сторін для згенерованого відео, можна вибрати `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`.
* `resolution`: вихідна роздільна здатність, можна вибрати `480p` (за замовчуванням), `720p` або `1080p`.
* `duration`: тривалість згенерованого відео (секунди). `grok-imagine-video-1.5-fast:reverse` має діапазон 6–30, інші моделі - 1–15, за замовчуванням 6. Рекомендується використовувати 6 секунд або 10 секунд, ці два стандартні часи є відносно стабільними.
* `callback_url`: адреса асинхронного зворотного виклику, після налаштування API негайно поверне `task_id`, а після завершення завдання результат буде надіслано на цю адресу.
* `async`: необов'язково, якщо встановити в `true`, інтерфейс негайно поверне `task_id`, не потрібно надавати `callback_url`, потім через відповідний інтерфейс запиту завдань можна опитувати для отримання результатів.

Натисніть кнопку «Спробувати», щоб протестувати, отримані результати будуть схожі на такі:

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

У відповіді є кілька полів, описаних нижче:

* `success`: чи була успішною запит на генерацію відео.
* `task_id`: ID завдання на генерацію відео.
* `trace_id`: ID відстеження запиту, використовується для усунення неполадок.
* `data`: список результатів згенерованого відео.
  * `id`: унікальний ідентифікатор згенерованого відео.
  * `video_url`: адреса посилання на згенероване відео.
  * `state`: стан завдання на генерацію відео, можливі значення `pending` / `succeeded` / `failed`.

Нам потрібно лише отримати згенероване відео за адресою `video_url` з результату `data`.

Відповідний код CURL виглядає так:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/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": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

Відповідний код Python виглядає так:

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/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": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

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

## Відео, згенероване з зображення

Якщо ви хочете згенерувати відео на основі вхідного зображення, ви можете передати `image_url`. При використанні `grok-imagine-video-1.5:official` це поле обов'язкове:

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## Направлення за допомогою референсних зображень

Якщо ви хочете використовувати одне або кілька референсних зображень для направлення стилю або вмісту відео, ви можете передати масив посилань на зображення в `reference_image_urls`:

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

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

Відео генерація потребує певного часу обробки. Якщо ви не хочете підтримувати довге з'єднання в очікуванні, ви можете передати `callback_url`, у цьому випадку API негайно поверне `task_id`, а після завершення завдання надішле остаточний результат на цю адресу:

```json theme={null}
{
  "prompt": "Кінематографічний кадр кошеняти, що переслідує метелика в сонячному саду",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

Негайно повернуті результати виглядають так:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

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

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

## Опис тарифікації

Спосіб тарифікації цієї послуги визначається `model`:

* `grok-imagine-video-1.5-fast:reverse`: тарифікація за тривалістю, не залежить від роздільної здатності — `6–10` секунд, `11–20` секунд, `21–30` секунд відповідають різним ціновим категоріям.
* `grok-imagine-video:reverse`: тарифікація за «вихідними секундами», загальна ціна = одинична ціна × `duration`.
* `grok-imagine-video:official` та `grok-imagine-video-1.5:official`: офіційні кінцеві точки, тарифікація за «вихідними секундами», чим вища роздільна здатність, тим вища одинична ціна; офіційні моделі навіть у разі невдачі перевірки контенту також будуть тарифікуватися.

Конкретна одинична ціна визначається на сторінці цін. Невдалі запити не тарифікуються і не займають безкоштовну квоту.

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

Коли запит має проблеми, API поверне відповідний код помилки та опис, найбільш поширені з них:

* `400`: параметри запиту некоректні, наприклад, у відео без тексту відсутній `prompt`, або `grok-imagine-video-1.5:official` без `image_url`, або `duration` виходить за межі (для `grok-imagine-video-1.5-fast:reverse` 6–30, для інших моделей 1–15).
* `401`: невдала аутентифікація, токен недійсний або не відповідає API.
* `403`: недостатньо коштів, або підказка потрапила під перевірку контенту і була відхилена.
* `429`: запити занадто часті, будь ласка, спробуйте пізніше.
* `500`: невдала генерація відео або аномалія в сервісі.


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