> ## 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`, затем через соответствующий интерфейс запроса задачи можно опрашивать для получения результата.

Нажмите кнопку «Try», чтобы протестировать, и полученный результат будет похож на следующий:

```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`，任务完成后会将最终结果 POST 到该 адрес：

```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`：鉴权失败，token 无效或与 API 不匹配。
* `403`：余额不足，或提示词命中内容审核被拒绝。
* `429`：请求过于频繁，请稍后重试。
* `500`：视频生成失败或服务异常。


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