Skip to main content

Grok Imagine Video

Grok Imagine Video is xAI’s video model family. It generates a clip from a prompt, animates a still image, or carries people, objects and voices from references into a new scene. Clips carry a soundtrack with lip-synced speech by default. One route serves every task, and the inputs you send decide which task you get. Generation is asynchronous. You submit a request, poll it until the status is terminal, then download the clip. The route mirrors xAI’s own API, so the request and response shapes are the provider’s.
Best for
  • Native 1080p. Grok Imagine Video 1.5 renders 1080p text-to-video and image-to-video.
  • Low cost per second. Grok Imagine Video 1.5 Lite is the cheapest way to draft a clip.
  • Characters that speak. Reference-to-video on 1.5 takes up to 14 reference images and up to 3 preset voices.
  • Storyboards. On 1.5, pin the first frame, the last frame and up to 4 frames in between.

Models

Durations are whole seconds. Lite reaches 1080p by upscaling a 720p render. The fields you send select the task: On 1.5, image combined with references or pins becomes the pinned first frame.

Endpoints

Request

Send your API key in the X-API-Key header. See Authentication. Set Content-Type: application/json. The examples also send a User-Agent header that names your application. The route accepts only the fields below. A body with any other top-level field, such as xAI’s output, storage_options or user, returns 400 before any charge.
string
required
The model ID: grok-imagine-video-1.5 or grok-imagine-video-1.5-lite.
string
The scene, up to 20,000 characters. Required on text-to-video. Optional when the body carries an image, a reference or a pinned frame. On reference-to-video, name the references by position: <IMAGE_0>, <IMAGE_1> and so on for images, <AUDIO_0> to <AUDIO_2> for voices. When image is also set, it takes <IMAGE_0> and the reference images start at <IMAGE_1>.
integer
default:"8"
The clip length in whole seconds, 1 to 15. You are billed per second of output.
string
default:"480p"
The output tier: 480p, 720p or 1080p. A body with references, last_frame or keyframes takes 480p or 720p only. A higher tier costs more per second. The tier names the frame height only roughly: a 16:9 clip at 1080p comes out 1920x1088.
string
default:"16:9"
The output shape: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 or 5:2. Image-to-video ignores it and follows the image.
boolean
default:"true"
Whether the clip carries a soundtrack. Send false for a silent clip. The price per second is the same either way.
object
The image to animate, or on 1.5 the pinned first frame. Holds url: a public https URL or a base64 data:image/... URI. xAI’s file_id is rejected.
object[]
Grok Imagine Video 1.5 only. 1 to 14 images that guide the subject, clothing or set without fixing the first frame. Each item holds url, as on image.
object[]
Grok Imagine Video 1.5 only. 1 to 3 preset voices. Each item is {"voice_id": "<voice>"}, such as eve. Voice IDs are case-insensitive, and an unknown one returns 400 with the list of voices. Your own audio files are not accepted: an item with url returns 400.
object
Grok Imagine Video 1.5 only. The image the clip ends on. Holds url, as on image.
object[]
Grok Imagine Video 1.5 only. 1 to 4 frames the clip passes through. Each item holds image (an object with url) and timestamp_s, a time in seconds strictly greater than 0 and less than duration. xAI snaps the times to a one-third-second grid, so keep two keyframes at least 1/3 s apart.

Response

Submit

A 200 status means that xAI accepted the request. It does not mean that the clip is ready.
string
required
The request ID. Poll GET /v1/xai/videos/{request_id} with it. It works for 7 days.

Poll

string
required
pending while the clip renders. done or failed when it ends. Poll until you read one of the two terminal values.
string
The URL of the clip. Present when status is done. The URL is time-limited. Download the clip as soon as the request is done. A later poll returns a fresh URL. It is null when xAI’s moderation filtered the clip.
number
The length of the clip in seconds, as billed.
boolean
false when xAI’s moderation filtered the clip. The request is then done, billed, and has no URL.
object
Present when status is failed. error.message explains why. Read it before you resubmit.

Example

Submit, poll, download. The submit and the poll use different paths.
The bodies below replace the submit body in the example. Image-to-video works on both models. Reference-to-video and pinned frames need Grok Imagine Video 1.5 and run at 720p or below.

Tips

  • Draft on Grok Imagine Video 1.5 Lite at 480p. It costs a fraction of 1.5 per second. Move to 1.5 or 1080p once the prompt works.
  • Keep the cast small on reference-to-video. Give each reference one role and a fixed place in the scene.
  • Check video.url before you download. A clip filtered by moderation ends as done with no URL.
  • Poll every 5 seconds at first, then back off to 30 seconds. Polls are free and never use a concurrency slot.

Errors and limits

A 200 status on submit means that xAI accepted the request. It does not mean that the clip succeeded. A request that fails later ends with status set to failed, and error.message explains why. Read it before you resubmit. A clip that xAI’s moderation filters ends with status set to done, video.url set to null and video.respect_moderation set to false. It is billed. A failed submit returns an HTTP error status. See Error codes. These request shapes are rejected with 400 before any charge: A 5xx status or a timeout on submit does not tell you whether the request was created. Never resubmit blindly. If the submit returned a request_id, poll it. If it returned nothing, check your credits before you try again. xAI bills per second of output at the chosen resolution, plus a fee for each input image: image, last_frame, each keyframe and each reference image. Preset voices are free. Nunchux holds the charge at submit and settles the seconds to the length xAI reports when the clip is done. The image fee stays. A failed request is refunded. See the pricing page for the rates. Every submit counts toward the simultaneous-jobs cap of your plan for six minutes, however fast the request finishes. A request that ends sooner does not give its slot back early, so a burst of short requests can return 429 concurrent_limit_exceeded. Wait and retry with backoff. Separately, at most five Grok Imagine requests per account can be in progress at once. A sixth returns 429 with the code too_many_open_tasks. A request stops counting toward the five when Nunchux settles it, which can be a few seconds after the poll first shows a terminal status, so a submit sent at once can still return 429. See Rate limits, Credits & pricing and the Partner models overview.