Grok Imagine Video API

Grok video: from a description, from a picture or from references, editing and continuing your clip. Two models: Grok with clips up to 30 seconds and Grok Pro.

Developer: xAIModel key in the API: grok_video

For AI assistants:Download .md All documentation .md Open as text

Connect in three steps

Get a keyCreate a key in the dashboard after you confirm your email. One key opens every model.
Check the pricePOST /v1/price shows the cost of a run in advance, without charging you.
Run a task and collect the resultPOST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files.

Ready-to-use code

Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded.

cURLPythonNode.js

cURL

curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import time

import requests

API = "https://api.cyhub.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

body = {
    "model": "grok_video",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
        "model": "grok",
        "aspect_ratio": "16:9",
        "duration": 10,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])

Node.js

const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();

Get a key

Price before the run

Prices as of 15.10.2026: from 8 ₽. POST /v1/price shows the exact price of your settings.

Mode	Price
From a description	from 8 ₽
Grok model = grok	from 18 ₽
Grok Pro model = grok_pro	from 8 ₽
From a picture	from 9 ₽
Grok model = grok	from 9 ₽
Grok Pro model = grok_pro	from 9 ₽
Video editing with a 1 s file	from 12 ₽
Video continuation with a 2 s file	from 44 ₽

Send the same settings to POST /v1/price: the response shows the price of the run without charging you.

cURL

curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}'

amount_minor: the price of the run in minor units (kopecks for rubles)
currency: the wallet currency
available_minor: how much your balance has for new tasks right now

Modes

Each mode has its own parameters and examples. The mode is set by the mode field.

From a description mode = text_to_video
From a picture mode = image_to_video
Video editing mode = video_to_video
Video continuation mode = video_extend

From a description

A video from text alone, no files are sent.

Value of the mode field: text_to_video

Price in this mode from 8 ₽.

Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

promptRequired: What happens in the video. Up to 5000 characters for Grok, up to 4096 Latin characters for Grok Pro, which counts a Cyrillic letter as two.
Type: StringMinimum characters: 1Maximum characters: 5000
modelOptional: The model. Grok is cheaper, a clip up to 30 seconds, has generation modes. Grok Pro gives higher quality, a clip up to 15 seconds.
Type: StringAllowed values: grokgrok_proDefault: "grok"
generation_modeOptional: The mood of a Grok clip, see the options. Grok Pro has no moods, keep "Normal".
Type: StringAllowed values: normalfunspicyDefault: "normal"
aspect_ratioOptional: Aspect ratio. Grok Pro has more of them: 4:3 and 3:4 too.
Type: StringAllowed values: 16:99:161:13:22:3The set depends on model.
Exceptions
model aspect_ratio
grok_pro plus 4:3, 3:4
Default: "9:16"
qualityOptional: Video resolution. 720p costs more.
Type: StringAllowed values: 480p720pDefault: "480p"
durationOptional: Video length in seconds: 6 to 30 for Grok, 1 to 15 for Grok Pro. The price is per second.
Type: IntegerMinimum: 1Maximum: 30Default: 6

`model`	`aspect_ratio`
`grok_pro`	plus `4:3`, `3:4`

Parameters not listed here are not accepted: the response is 422 unknown_setting.

The API sets these settings itself, do not send them: files_as_is = true

Input

Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

A video from a description

JSON

{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}

Grok Pro in 720p

JSON

{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бармен подбрасывает шейкер и ловит его за спиной, тёплый свет бара",
    "model": "grok_pro",
    "aspect_ratio": "4:3",
    "quality": "720p",
    "duration": 8
  }
}

The price is calculated when the task is accepted, currency RUB.

Complete generation example

Output

One MP4 video.
Generation takes 2 to 5 minutes.

Kind	Formats	How many	Note
`video`	mp4	1

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

JSON

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}

How to read the result and download files

From a picture

The video starts from your picture, or the model takes characters and objects from reference pictures. A picture or at least one reference is needed.

Value of the mode field: image_to_video

Price in this mode from 9 ₽.

Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

promptRequired: What happens in the video. Up to 4096 characters, up to 5000 for Grok with references. Grok Pro counts a Cyrillic letter as two.
Type: StringMinimum characters: 1Maximum characters: 5000
modelOptional: The model. Grok is cheaper, a clip up to 30 seconds, has generation modes. Grok Pro gives higher quality, a clip up to 15 seconds.
Type: StringAllowed values: grokgrok_proDefault: "grok"
image_urlsOptional: One URL of the picture the video starts from. May be left out when references are given.
Type: List (String, uri)Maximum items: 1
reference_image_urlsOptional: Up to 7 URLs of pictures with characters, objects or a style. Grok takes no more than 7 together with the main picture, Grok Pro does not take the main picture together with references.
Type: List (String, uri)Maximum items: 7
generation_modeOptional: The mood of the clip: "Normal" or "Fun". Works only for Grok with references, otherwise keep "Normal".
Type: StringAllowed values: normalfunDefault: "normal"
aspect_ratioOptional: Aspect ratio. Auto is only for Grok with one main picture and no references, 4:3 and 3:4 are not available for Grok with references.
Type: StringAllowed values: 16:99:161:14:33:43:22:3autoThe set depends on model.
Exceptions
model aspect_ratio
grok_pro except auto
Default: "9:16"
qualityOptional: Video resolution. 720p costs more.
Type: StringAllowed values: 480p720pDefault: "480p"
durationOptional: Video length in seconds: 1 to 15, 6 to 30 for Grok with references, up to 10 for Grok Pro with references. The price is per second.
Type: IntegerMinimum: 1Maximum: 30Default: 6

`model`	`aspect_ratio`
`grok_pro`	except `auto`

Parameters not listed here are not accepted: the response is 422 unknown_setting.

The API sets these settings itself, do not send them: files_as_is = true

Input

Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each.
With one picture for Grok (the main one or a single reference), the aspect ratio comes from the picture. Grok Pro stretches the main picture to the chosen aspect ratio.

Field	Accepts	Formats	Files	File size up to
`image_urls`	Images	jpeg, jpg, png, webp	1	10 MB
`reference_image_urls`	Images	jpeg, jpg, png, webp	7	10 MB

How to send files

Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

Animate a picture

JSON

{
  "model": "grok_video",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Камера медленно наезжает, волосы героини развеваются на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 8
  }
}

A character from references

JSON

{
  "model": "grok_video",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Этот персонаж в этом пальто идёт по ночному городу под дождём",
    "model": "grok_pro",
    "duration": 8,
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/coat.png"
    ]
  }
}

The price is calculated when the task is accepted, currency RUB.

Complete generation example

Output

One MP4 video.
Generation takes 2 to 5 minutes.

Kind	Formats	How many	Note
`video`	mp4	1

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

JSON

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}

How to read the result and download files

Video editing

Grok Pro changes your clip by the description: clothes, objects, colours. The model tries to keep the rest of the shot.

Value of the mode field: video_to_video

Price in this mode from 12 ₽, with a 1 s file.

Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

promptRequired: What to change in the clip, up to 4096 Latin characters: a Cyrillic letter counts as two.
Type: StringMinimum characters: 1Maximum characters: 4096
video_urlsRequired: One URL of an MP4 clip no longer than 8.7 seconds.
Type: List (String, uri)Maximum items: 1

Parameters not listed here are not accepted: the response is 422 unknown_setting.

The API sets these settings itself, do not send them: files_as_is = true model = "grok_pro"

Input

The clip is a URL of an MP4 file, and the URL must end in .mp4. At most 8.7 seconds long, the whole clip is sent, there is no trimming.
xAI names no size limit, 50 MB is our recommendation, not its limit.
The price is per second of the source clip, a started second counts as a whole one. It is counted as for 720p.

Field	Accepts	Formats	Files	File size up to
`video_urls`	Video	mp4	1	50 MB

How to send files

Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

Put on a hat

JSON

{
  "model": "grok_video",
  "settings": {
    "mode": "video_to_video",
    "prompt": "Надень на героиню широкополую чёрную шляпу",
    "video_urls": [
      "https://example.com/clip.mp4"
    ]
  }
}

The price is calculated when the task is accepted, currency RUB.

Complete generation example

Output

One MP4 video.
Generation takes 2 to 5 minutes.
The length and aspect ratio of the source clip, its resolution too, but no higher than 720p.

Kind	Formats	How many	Note
`video`	mp4	1

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

JSON

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}

How to read the result and download files

Video continuation

Grok Pro continues your clip from its last frame by a description of what happens next.

Value of the mode field: video_extend

Price in this mode from 44 ₽, with a 2 s file.

Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

promptRequired: What happens next, up to 4096 Latin characters: a Cyrillic letter counts as two.
Type: StringMinimum characters: 1Maximum characters: 4096
video_urlsRequired: One URL of an MP4 clip 2 to 15 seconds long.
Type: List (String, uri)Maximum items: 1
durationOptional: Length of the continuation in seconds, 2 to 10. Every second of the continuation adds to the price.
Type: IntegerMinimum: 2Maximum: 10Default: 6

Parameters not listed here are not accepted: the response is 422 unknown_setting.

The API sets these settings itself, do not send them: files_as_is = true model = "grok_pro"

Input

The clip is a URL of an MP4 file, and the URL must end in .mp4. 2 to 15 seconds long, the whole clip is sent, there is no trimming.
xAI names no size limit, 50 MB is our recommendation, not its limit.
The price covers the seconds of the source clip and the seconds of the finished video, that is the source together with the continuation. A started second counts as a whole one, the price is as for 720p.

Field	Accepts	Formats	Files	File size up to
`video_urls`	Video	mp4	1	50 MB

How to send files

Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

Continue a clip

JSON

{
  "model": "grok_video",
  "settings": {
    "mode": "video_extend",
    "prompt": "Камера отъезжает и показывает весь город с высоты",
    "video_urls": [
      "https://example.com/clip.mp4"
    ],
    "duration": 6
  }
}

The price is calculated when the task is accepted, currency RUB.

Complete generation example

Output

One MP4 video.
Generation takes 2 to 5 minutes.
The finished video is the source clip together with the continuation. The aspect ratio and resolution of the source, but no higher than 720p.

Kind	Formats	How many	Note
`video`	mp4	1

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

JSON

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}

How to read the result and download files

Try Grok Imagine Video through the API

One key opens every CyHUB model. Payment in rubles, and you see the price before the run.

Get an API key

Grok Imagine Video API

Connect in three steps

Ready-to-use code

Price before the run

Modes

From a description

Parameters

Input

Request example

Output

From a picture

Parameters

Input

Request example

Output

Video editing

Parameters

Input

Request example

Output

Video continuation

Parameters

Input

Request example

Output

See also

Try Grok Imagine Video through the API