88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Video

Grok Video API

Resolution, duration and ratio for grok-imagine-video and grok-imagine-video-1.5, and how to use first frames, last frames, keyframes, reference images and reference voices.

This page specifies the xAI Grok video models grok-imagine-video and grok-imagine-video-1.5. They share the POST /v1/videos create and GET /v1/videos/{id} polling flow with the other video models; authentication, polling states, downloads and error handling are covered in the Complete Video API Standard. This page lists only the fields and rules specific to Grok.

Updated 2026-10-27. grok-imagine-video-1.5 supports last frames, keyframes, reference images and reference voices, and grok-imagine-video supports reference images. The former grok-imagine-video-1.5-1080p is retired; for 1080P use grok-imagine-video-1.5 with "resolution": "1080p". Grok supports polling only; do not send callback_url.

Models

ModelResolutionDurationRatioInputs
grok-imagine-video480P / 720P, default 720P1–15s, default 8s; 1–10s with reference images16:9 9:16 1:1 4:3 3:4 3:2 2:3, default 16:9one first frame, or up to 14 reference images (not both)
grok-imagine-video-1.5480P / 720P / 1080P, default 720P; at most 720P with a last frame, keyframes, reference images or reference voices1–15s, default 8ssameone first frame, one last frame, up to 4 keyframes, up to 14 reference images and up to 3 reference voices, in any combination

Basic parameters

  • Resolution: resolution is 480p or 720p, plus 1080p for grok-imagine-video-1.5. It can also be sent as metadata.resolution.
  • Duration: whole seconds in duration (or the string seconds).
  • Aspect ratio: aspect_ratio and ratio are equivalent, and you can also put the ratio in size (for example "size": "9:16"); size does not accept pixel dimensions. If you send more than one ratio field (including those in metadata), the values must match, otherwise the request returns 400. A first or last frame whose ratio differs from aspect_ratio is center-cropped.
  • Prompt: send a prompt, an input, or both; a request with neither returns 400. When you only use reference voices, describe the scene and the lines in the prompt.

Input fields

InputFieldgrok-imagine-video-1.5grok-imagine-video
First frameimage, images, input_reference or metadata.firstFrame11
Last framelast_frame or metadata.lastFrame1not supported
Keyframeskeyframes or metadata.keyframesup to 4not supported
Reference imagesreference_images or metadata.referenceImagesup to 14up to 14, not together with a first frame
Reference voicesreference_audios or metadata.referenceAudiosup to 3not supported
  • Format: an image is a URL string or {"url": "..."}; keyframes are [{"image": "…", "timestamp_s": 2}]; reference images are an array of image URLs; reference voices are an array of voice names, for example ["eve"].
  • Image URLs: every image must be a public https:// URL. Base64 and multipart/form-data file uploads are not accepted.
  • One first frame: images holds a single image, which is used as the first frame; more than one image across the first-frame fields returns 400. Put several images in reference_images.
  • Separate limits: the first frame, last frame and keyframes do not count toward the 14 reference images.
  • Last frame only: you can omit the first frame and only set the closing shot with last_frame. Sending the same image as the first and last frame makes a loop.
  • Keyframe times: timestamp_s must be greater than 0 and less than duration. Frames snap to a 1/3-second grid, so two keyframes must be at least 1/3 second apart, otherwise the request returns 400. Set the opening and closing shots with the first and last frame, not in keyframes.
  • Using reference images: refer to them in the prompt in order as <IMAGE_0>, <IMAGE_1>, and so on. When a first frame is also sent, it is <IMAGE_0> and the reference images start at <IMAGE_1>. Reference images do not fix the opening shot; send a first frame as well when you need one.
  • Using reference voices: refer to them in the prompt as <AUDIO_0>, <AUDIO_1>, and so on. Only these preset voices are available (case-insensitive); custom and cloned voices are not supported: altair ara atlas aurora carina castor celeste cosmo eve helios helix iris kepler leo liora lumen luna lux naksh orion perseus rex rigel sal sirius ursa zagan zenith.
  • Resolution and duration: with a last frame, keyframes, reference images or reference voices, grok-imagine-video-1.5 goes up to 720P, and grok-imagine-video with reference images goes up to 10 seconds. Text-only and first-frame requests have no such limits.
  • Not supported: reference video, negative_prompt, seed and generate_audio.

Text to video

{
  "model": "grok-imagine-video-1.5",
  "prompt": "A silver sports car in a rainy city at night, low tracking shot, neon reflections, cinematic",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}

Image to video (first frame)

{
  "model": "grok-imagine-video",
  "prompt": "Keep the subject of the image and slowly pull back from a close-up, cinematic",
  "duration": 6,
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "images": ["https://cdn.example.com/start.jpg"]
}

First and last frame

{
  "model": "grok-imagine-video-1.5",
  "prompt": "The camera dollies from the sunlit doorway to the window",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "image": "https://cdn.example.com/start.jpg",
  "last_frame": "https://cdn.example.com/end.jpg"
}

Keyframes

Set the shots at seconds 2 and 4 between the first and last frame:

{
  "model": "grok-imagine-video-1.5",
  "prompt": "A slow dolly through the room as the light changes",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "image": "https://cdn.example.com/start.jpg",
  "keyframes": [
    { "image": "https://cdn.example.com/second-2.jpg", "timestamp_s": 2 },
    { "image": "https://cdn.example.com/second-4.jpg", "timestamp_s": 4 }
  ],
  "last_frame": "https://cdn.example.com/end.jpg"
}

Reference images and voices

{
  "model": "grok-imagine-video-1.5",
  "prompt": "The model from <IMAGE_0> walks the runway in the shirt from <IMAGE_1> and presents it with the voice from <AUDIO_0>",
  "duration": 8,
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "reference_images": [
    "https://cdn.example.com/model.jpg",
    "https://cdn.example.com/shirt.jpg"
  ],
  "reference_audios": ["eve"]
}

grok-imagine-video can also use reference images on their own (no first frame, up to 10 seconds):

{
  "model": "grok-imagine-video",
  "prompt": "The puppy from <IMAGE_0> runs along the beach from <IMAGE_1>",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "reference_images": [
    "https://cdn.example.com/dog.jpg",
    "https://cdn.example.com/beach.jpg"
  ]
}