Grok Imagine video

grok-imagine-video-1.5 turns text into video, with optional reference images: submit a task, poll its ID, then download the finished clip.

Grok Imagine images use the synchronous OpenAI Images endpoints, and their parameters do not carry over to video; see Grok Imagine images.

Available models

grok-imagine-video-1.5 is text-to-video with optional reference images: no first / last frames, and no reference video or audio.

Images and chat are served by the Grok Suite group; video is served by the Grok Video group. They are two separate groups: a key reaches the video model only if it includes Grok Video, and one key can include both groups — confirm with GET /v1/models using the key you actually intend to use.

Official prices for each resolution tier and for reference images are on the model card: grok-imagine-video-1.5. Every video field is listed in the API reference under Submit a video task.

Request parameters

• model must match exactly.
• content is an array of text items with non-empty text; it accepts no image / video / audio items.
• resolution is billed per second at its tier; with reference_images, only 480p / 720p.
• The duration and aspect_ratio defaults are filled by the service, and billing follows the finished duration_seconds.
• Use aspect_ratio for the frame; ratio is rejected.
• reference_images is a top-level array, public HTTP(S) only, no Data URL / asset://; each reference image is billed separately.

ratio, frames, seed, camera_fixed, draft, draft_task, service_tier, generate_audio, watermark, and return_last_frame are rejected. Other unlisted fields (such as a top-level image) are not checked and do not act as references.

Response

Video uses the same task envelope as Seedance; do not read a top-level id as for Kling.

Submit response

A successful submit returns 200 with the task ID in task.id (shaped like vt…):

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "pending",
    "outputs": []
  }
}

Task query fields

Poll GET /v1/video/tasks/{task_id} with task.id.

Only completed and failed are terminal, so treat any other value as still running.

In progress

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "processing",
    "outputs": [],
    "error": null
  }
}

Succeeded

A completed task carries duration_seconds and the video URLs in outputs:

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "completed",
    "duration_seconds": 5,
    "outputs": [
      "https://api.hop-base.com/example-signed-video.mp4"
    ],
    "error": null
  },
  "usage": { "cost": 1.02, "cost_usd": 0.15, "currency": "CNY" }
}

Failed

Execution failures still query as HTTP 200; check task.status and task.error.message:

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "failed",
    "outputs": [],
    "error": { "message": "<English failure reason>" }
  }
}

Minimal example

# 1. Submit
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "An orange cat runs across sunlit grass as the camera follows",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

# 2. Poll with the returned task.id
curl https://api.hop-base.com/v1/video/tasks/vt-your-task-id \
  -H "Authorization: Bearer sk-your-key"

Notes

• outputs stays valid for 24 hours from completion; querying again does not extend it, and an expired URL returns 410. Download and save results promptly.
• A moderated prompt fails the task with content-moderated in error.message.
• With reference_images, the resolution can only be 480p / 720p.
• Reference images must be public HTTP(S) URLs, and the maximum count has not been verified.
• Video is in a different group from images and chat; add the Grok Video group to your key to call it.

Common errors and fixes

Submission errors are 400 with only error.message (no code).

Full error texts:

grok-imagine-video-1.5 requires resolution: 480p / 720p / 1080p
model grok-imagine-video-1.5 does not support resolution 4k
grok-imagine-video-1.5 duration must be an integer in 1-15, got 20
grok-imagine-video-1.5 uses aspect_ratio for the frame ratio and does not support ratio
aspect_ratio must be one of 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3, got 21:9
grok-imagine-video-1.5 does not support parameter generate_audio
grok-imagine-video-1.5 only supports text segments in content; use reference_images for reference images
reference_images[0] must be a {"url": "..."} object
reference_images[0].url must be a publicly reachable http(s) address
grok-imagine-video-1.5 reference-to-video supports up to 720p; remove the reference images or choose 480p/720p
priority must be within 0-9, got 12
execution_expires_after must be within 3600-259200 seconds
callback_url must be a valid http(s) URL
safety_identifier must be an ASCII string of 1-64 characters

Billing

Billing is per second of finished footage, priced by resolution tier; each reference image is billed separately. Failed tasks are not billed.

Once the task finishes, the query's top-level usage also carries cost_usd — the USD amount actually deducted from your balance for this task, 0 for an uncharged failure — cost (the same charge in CNY), and currency (always CNY). For the balance check at submission (402 when it falls short) and the other rules shared by every video task, see Video overview.

Official list prices are on the pricing page. Your own rate is the one shown in the signed-in Model Plaza, and each request's actual charge is on the Usage page in the console.

Next steps

• Grok Imagine images: generate and edit images
• Video overview: compare video families and the shared task flow
• Grok: Grok chat and reasoning models, including long-context pricing, reasoning-token billing, and server-side tool charges
• Error codes and retries: what each error code means and whether to retry