Grok Imagine Video

grok-imagine-video-1.5-preview uses the OpenAI-compatible video task API. It is an image-to-video model, so every request must include at least one reference image.

Endpoints

Capability	Method	Path
Create video task	POST	/v1/videos
Retrieve video task	GET	/v1/videos/{video_id}
Download video file	GET	/v1/videos/{video_id}/content

Supported Model

Model	Description
grok-imagine-video-1.5-preview	Grok Imagine 1.5 preview image-to-video model. Requires image input

Actual availability depends on account permissions and platform configuration.

Supported Modes

Mode	How to call
Image to video	Provide at least one reference image by JSON or multipart upload
Multiple reference images	Repeat input_reference[] in multipart requests, or pass multiple references in JSON when supported by your client
Video download	Poll the task, then call /v1/videos/{video_id}/content after completion

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	Use grok-imagine-video-1.5-preview
prompt	string	Yes	Video generation prompt
seconds	string or integer	No	Duration. Supported values: 6, 10, 12, 16, 20. Defaults to 6
size	string	No	Video size. Defaults to 720x1280
resolution_name	string	No	480p or 720p. If omitted, it is selected from size
preset	string	No	custom, normal, fun, or spicy. Defaults to custom
input_reference	string, object, or array	Yes	Reference image input in JSON requests. Supports image URLs or data URIs
image	string or object	No	Single reference image, equivalent to one input_reference
image_url	string	No	Single reference image URL, equivalent to one input_reference
input_reference[]	file[]	Yes	Reference image file field for multipart/form-data. At most the first 7 images are used

Provide at least one of input_reference, image, image_url, or input_reference[]. grok-imagine-video-1.5-preview does not accept text-only video requests.

Supported Sizes

size	Ratio	Default resolution
720x1280	9:16	720p
1280x720	16:9	720p
1024x1024	1:1	720p
1024x1792	9:16	720p
1792x1024	16:9	720p

Examples

JSON Request

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "prompt": "A gentle cinematic camera push over the reference image, soft light, realistic motion",
    "seconds": "6",
    "size": "720x1280",
    "preset": "custom",
    "input_reference": {
      "image_url": "https://example.com/reference.png"
    }
  }'

You can also pass a single image URL directly:

{
  "model": "grok-imagine-video-1.5-preview",
  "prompt": "Make the product slowly rotate in a clean studio scene",
  "seconds": "10",
  "size": "1280x720",
  "image_url": "https://example.com/product.png"
}

File Upload

For multipart/form-data, use input_reference[] as the reference image field:

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=grok-imagine-video-1.5-preview" \
  -F "prompt=A cinematic product shot with a slow dolly move" \
  -F "seconds=6" \
  -F "size=720x1280" \
  -F "preset=custom" \
  -F "input_reference[]=@reference.png"

Repeat input_reference[] for multiple reference images. At most the first 7 images are used.

Response and Retrieval

A successful create request returns an asynchronous video task:

{
  "id": "video_xxx",
  "object": "video",
  "created_at": 1770000000,
  "status": "queued",
  "model": "grok-imagine-video-1.5-preview",
  "progress": 0,
  "prompt": "A gentle cinematic camera push over the reference image",
  "seconds": "6",
  "size": "720x1280",
  "quality": "standard"
}

Save id for polling and downloading the video.

Retrieve the task:

curl https://cubicspaces.cloud/v1/videos/video_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

While generating:

{
  "id": "video_xxx",
  "object": "video",
  "status": "queued",
  "model": "grok-imagine-video-1.5-preview",
  "progress": 35,
  "seconds": "6",
  "size": "720x1280",
  "quality": "standard"
}

After completion:

{
  "id": "video_xxx",
  "object": "video",
  "status": "completed",
  "model": "grok-imagine-video-1.5-preview",
  "progress": 100,
  "completed_at": 1770000060,
  "seconds": "6",
  "size": "720x1280",
  "quality": "standard"
}

Download Video Content

After the task is completed, call /content to download the final MP4:

curl -L https://cubicspaces.cloud/v1/videos/video_xxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o grok-video.mp4

SDK Examples

Python

import time
import requests

base_url = "https://cubicspaces.cloud/v1"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

task = requests.post(
    f"{base_url}/videos",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5-preview",
        "prompt": "A gentle cinematic camera push over the reference image",
        "seconds": "6",
        "size": "720x1280",
        "input_reference": {
            "image_url": "https://example.com/reference.png"
        },
    },
).json()

video_id = task["id"]

while True:
    current = requests.get(f"{base_url}/videos/{video_id}", headers=headers).json()
    if current["status"] == "completed":
        break
    if current["status"] == "failed":
        raise RuntimeError(current.get("error", {}).get("message", "video failed"))
    time.sleep(5)

content = requests.get(f"{base_url}/videos/{video_id}/content", headers=headers).content
with open("grok-video.mp4", "wb") as f:
    f.write(content)

Node.js

import fs from "node:fs/promises";

const baseURL = "https://cubicspaces.cloud/v1";
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};

const taskResponse = await fetch(`${baseURL}/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "grok-imagine-video-1.5-preview",
    prompt: "A gentle cinematic camera push over the reference image",
    seconds: "6",
    size: "720x1280",
    input_reference: {
      image_url: "https://example.com/reference.png"
    }
  })
});
const task = await taskResponse.json();

while (true) {
  const currentResponse = await fetch(`${baseURL}/videos/${task.id}`, { headers });
  const current = await currentResponse.json();
  if (current.status === "completed") break;
  if (current.status === "failed") {
    throw new Error(current.error?.message || "video failed");
  }
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

const response = await fetch(`${baseURL}/videos/${task.id}/content`, { headers });
await fs.writeFile("grok-video.mp4", Buffer.from(await response.arrayBuffer()));

Common Errors

Error	Meaning
Model 'grok-imagine-video-1.5-preview' requires at least one input image	No reference image was provided
seconds must be one of [6, 10, 12, 16, 20]	seconds is not supported
size must be one of [...]	size is not supported
resolution_name must be one of [480p, 720p]	Unsupported resolution parameter

Notes

• grok-imagine-video-1.5-preview requires a reference image. Do not send text-only video requests.
• JSON requests can use public image URLs or data:image/...;base64,....
• For local file uploads, use multipart/form-data and the field name input_reference[].
• Video generation is asynchronous. Save id and poll the retrieve endpoint.
• Download the final MP4 from /v1/videos/{video_id}/content after completion.