Перейти к основному содержанию
POST
Submit a video generation task (text-to-video / image-to-video)
🔒 Требуется группа GrokOfficial, доступ предоставляется по заявке: Grok Imagine Video не входит в группу Default; перед вызовом необходимо запросить доступ (включая Playground на этой странице). Без доступа или с pay-per-request token каждый вызов возвращает 503. См. раздел Обзор Grok Imagine Video — настройка группы.
Интерактивный Playground справа позволяет протестировать эндпоинт напрямую. Введите ваш API-ключ в Authorization (формат: Bearer sk-xxx), выберите model, заполните prompt / seconds / size и отправьте запрос; добавьте input_reference для image-to-video. Playground выполняет только шаг 1 (отправка) — получив id задачи, выполняйте опрос и скачивание, как показано ниже.
⚠️ Три самые распространенные ошибки
  1. Без size / seconds по умолчанию используются 480p и 8 секунд, и именно они тарифицируются.
  2. У grok-imagine-video нет разрешения 1080p: 1920x1080 возвращает 400; используйте -1.5 или -1.5-lite для 1080p.
  3. Блокировки модерации тарифицируются: заблокированная задача по-прежнему возвращает completed, но содержит error.code: "moderation_blocked" и не содержит видео.
Трехэтапный асинхронный процесс — эта страница описывает только шаг 1 (отправка)
  • Шаг 1 (эта страница): POST /v1/videos → возвращает id задачи + status: "queued"
  • Шаг 2: опрашивайте GET /v1/videos/{id}, пока status не примет значение "completed" или "failed"
  • Шаг 3: скачайте MP4 из GET /v1/videos/{id}/content
Отправка выполняется за считанные секунды и не ожидает готовности видео.

Примеры кода

Python (генерация видео по тексту, все три шага)

Python (генерация видео по изображению, входное изображение в base64)

cURL

Node.js (fetch)

Краткий справочник по параметрам

Цена за секунду (как у xAI):
Тарификация моделей синхронизирована с официальными сайтами и может изменяться вслед за ними; приведенная выше таблица носит исключительно справочный характер, а официальные данные представлены на вкладке Тарифы на модели в верхнем меню: Тарифы на модели.

Примеры ответов

Отправка (шаг 1):
Выполнено (результат опроса на шаге 2):
Заблокировано модерацией: status по-прежнему completed, но присутствует дополнительное поле error, а видео для скачивания отсутствует:

Связанная документация

Авторизации

Authorization
string
header
обязательно

API Key from the APIYI console (Token group must include GrokOfficial)

Тело

application/json
model
enum<string>
по умолчанию:grok-imagine-video-1.5-lite
обязательно

Model ID (billed per second × resolution rate):

  • grok-imagine-video — 480p $0.05/s, 720p $0.07/s, no 1080p
  • grok-imagine-video-1.5 — 480p $0.08, 720p $0.14, 1080p $0.25 per second
  • grok-imagine-video-1.5-lite — 480p $0.02, 720p $0.03, 1080p $0.14 per second
Доступные опции:
grok-imagine-video,
grok-imagine-video-1.5,
grok-imagine-video-1.5-lite
prompt
string

Prompt: scene + subject + action + camera + lighting. Required for text-to-video; for image-to-video it describes motion and camera

Пример:

"a red paper boat drifting on a calm lake, gentle ripples, soft morning light"

seconds
string

Duration from 1 to 15 seconds, as a string or a number; default 8. Out-of-range values return 400. Cost scales with seconds — use 1–2 seconds while testing.

Пример:

"2"

size
enum<string>
по умолчанию:854x480

Output size in WIDTHxHEIGHT pixels: the shorter side sets the resolution (≥1080 is 1080p, ≥720 is 720p, otherwise 480p) and the aspect ratio snaps to the nearest supported one. You can also pass 480p / 720p / 1080p directly. Without it, the default is 480p.

  • 854x480 — 480p landscape (measured 848×480)
  • 1280x720 / 720x1280 — 720p landscape / portrait
  • 1920x1080 / 1080x1920 — 1080p (1.5 / 1.5-lite only)
Доступные опции:
854x480,
480x854,
1280x720,
720x1280,
1920x1080,
1080x1920
input_reference
string

Input image for image-to-video: a public image URL or a data:image/jpeg;base64,... data URI. Passing it makes the job image-to-video, and the output frame follows the input image. Each input image costs an extra $0.002 (grok-imagine-video) or $0.01 (1.5 / 1.5-lite).

Пример:

"https://example.com/first-frame.jpg"

Ответ

Task submitted; returns the task id and queued status

id
string

Task ID for polling and download

Пример:

"task_xxxxxxxxxxxxxxxx"

object
string

Always video

Пример:

"video"

model
string
Пример:

"grok-imagine-video-1.5-lite"

status
enum<string>

Task status:

  • queued — submitted, waiting
  • in_progress — generating
  • completed — done, download from /v1/videos/{id}/content; with error.code: moderation_blocked it was blocked and has no video
  • failed — failed
Доступные опции:
queued,
in_progress,
completed,
failed
Пример:

"queued"

progress
integer

Progress 0–100, coarse-grained; not suitable for a precise progress bar

Пример:

0

seconds
string

Video duration, returned once done

created_at
integer

Task creation Unix timestamp (seconds)

completed_at
integer

Task completion Unix timestamp (seconds), returned once done