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.5supports last frames, keyframes, reference images and reference voices, andgrok-imagine-videosupports reference images. The formergrok-imagine-video-1.5-1080pis retired; for 1080P usegrok-imagine-video-1.5with"resolution": "1080p". Grok supports polling only; do not sendcallback_url.
Models
| Model | Resolution | Duration | Ratio | Inputs |
|---|---|---|---|---|
grok-imagine-video | 480P / 720P, default 720P | 1–15s, default 8s; 1–10s with reference images | 16:9 9:16 1:1 4:3 3:4 3:2 2:3, default 16:9 | one first frame, or up to 14 reference images (not both) |
grok-imagine-video-1.5 | 480P / 720P / 1080P, default 720P; at most 720P with a last frame, keyframes, reference images or reference voices | 1–15s, default 8s | same | one 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:
resolutionis480por720p, plus1080pforgrok-imagine-video-1.5. It can also be sent asmetadata.resolution. - Duration: whole seconds in
duration(or the stringseconds). - Aspect ratio:
aspect_ratioandratioare equivalent, and you can also put the ratio insize(for example"size": "9:16");sizedoes not accept pixel dimensions. If you send more than one ratio field (including those inmetadata), the values must match, otherwise the request returns 400. A first or last frame whose ratio differs fromaspect_ratiois 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
| Input | Field | grok-imagine-video-1.5 | grok-imagine-video |
|---|---|---|---|
| First frame | image, images, input_reference or metadata.firstFrame | 1 | 1 |
| Last frame | last_frame or metadata.lastFrame | 1 | not supported |
| Keyframes | keyframes or metadata.keyframes | up to 4 | not supported |
| Reference images | reference_images or metadata.referenceImages | up to 14 | up to 14, not together with a first frame |
| Reference voices | reference_audios or metadata.referenceAudios | up to 3 | not 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 andmultipart/form-datafile uploads are not accepted. - One first frame:
imagesholds a single image, which is used as the first frame; more than one image across the first-frame fields returns 400. Put several images inreference_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_smust be greater than 0 and less thanduration. 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 inkeyframes. - 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:altairaraatlasauroracarinacastorcelestecosmoevehelioshelixiriskeplerleolioralumenlunaluxnakshorionperseusrexrigelsalsiriusursazaganzenith. - Resolution and duration: with a last frame, keyframes, reference images or reference voices,
grok-imagine-video-1.5goes up to 720P, andgrok-imagine-videowith reference images goes up to 10 seconds. Text-only and first-frame requests have no such limits. - Not supported: reference video,
negative_prompt,seedandgenerate_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"
]
}