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

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

Чтобы использовать Grok Videos Generation API, сначала перейдите в консоль Ace Data Cloud, чтобы получить ваш API Token и сохранить его для дальнейшего использования. Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу. Один API Token позволяет использовать все услуги платформы, не нужно подавать отдельные заявки на каждую услугу. При первой подаче заявки предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в консоли.
📘 Полная документация: Grok Videos Generation API →

Описание моделей

Через model можно выбрать следующие четыре общедоступные модели. Их возможности и способы тарификации указаны ниже:
  • 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», чтобы протестировать, и полученный результат будет похож на следующий:
Возвращаемый результат содержит несколько полей, описание которых приведено ниже:
  • success: успешен ли запрос на генерацию видео.
  • task_id: ID задачи на генерацию видео.
  • trace_id: ID отслеживания запроса, используемый для устранения неполадок.
  • data: список результатов сгенерированного видео.
    • id: уникальный идентификатор сгенерированного видео.
    • video_url: ссылка на сгенерированное видео.
    • state: состояние задачи по генерации видео, может быть pending / succeeded / failed.
Нам нужно просто получить сгенерированное видео по ссылке video_url из результата data. Соответствующий код CURL выглядит следующим образом:
Соответствующий код на Python выглядит следующим образом:

Видео на основе изображений

Если вы хотите сгенерировать видео на основе входного изображения, вы можете передать image_url. При использовании grok-imagine-video-1.5:official это поле обязательно:

Направление с помощью эталонных изображений

Если вы хотите использовать одно или несколько эталонных изображений для направления стиля или содержания видео, вы можете передать массив ссылок на изображения в reference_image_urls:

Асинхронный обратный вызов

视频生成需要一定的处理时间。如果不希望保持长连接等待,可以传入 callback_url,此时 API 会立即返回 task_id,任务完成后会将最终结果 POST 到该 адрес:
立即返回的结果如下:

查询任务结果

如果使用了异步回调或希望主动查询任务状态,可以通过 Grok Tasks API(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:视频生成失败或服务异常。