Documentation 2026-07-31 15:02 UTC to 2026-08-01 01:59 UTC

321 321 

322# Video generation322# Video generation

323video = client.video.generate(323video = client.video.generate(

324 model="grok-imagine-video",324 model="grok-imagine-video-1.5",

325 prompt="A cat floating in space",325 prompt="A cat floating in space",

326)326)

327print(f"Video cost: ${video.cost_usd:.4f}")327print(f"Video cost: ${video.cost_usd:.4f}")

121console.log(image.base64);121console.log(image.base64);

122```122```

123 123 

124## Image-to-Video124## Video Generation

125 125 

126Animate a still image with a text prompt. The source image becomes the starting point for the generated video. Video requests are asynchronous: start a request, poll with the returned request ID, and use the completed video URL when ready. The xAI SDK and AI SDK handle polling for you.126Animate a still image with a text prompt. The source image becomes the starting point for the generated video. Video requests are asynchronous: start a request, poll with the returned request ID, and use the completed video URL when ready. The xAI SDK and AI SDK handle polling for you.

127 127 

193* **[Multi-Image Editing](/developers/model-capabilities/images/multi-image-editing)** — Combine up to 3 source images in a single edit for compositing subjects, transferring styles, and building scenes from multiple references.193* **[Multi-Image Editing](/developers/model-capabilities/images/multi-image-editing)** — Combine up to 3 source images in a single edit for compositing subjects, transferring styles, and building scenes from multiple references.

194* **[Video Generation](/developers/model-capabilities/video/generation)** — Generate videos from text prompts with configurable duration (up to 15s), aspect ratio, and resolution.194* **[Video Generation](/developers/model-capabilities/video/generation)** — Generate videos from text prompts with configurable duration (up to 15s), aspect ratio, and resolution.

195* **[Video Editing](/developers/model-capabilities/video/editing)** — Modify an existing video with a text prompt while preserving the rest of the scene.195* **[Video Editing](/developers/model-capabilities/video/editing)** — Modify an existing video with a text prompt while preserving the rest of the scene.

196* **[Reference-to-Video](/developers/model-capabilities/video/reference-to-video)** — Guide a generated video with one or more reference images that influence the output without forcing the first frame. Requires `grok-imagine-video` — `grok-imagine-video-1.5` does not support this mode.196* **[Reference-to-Video](/developers/model-capabilities/video/reference-to-video)** — Guide a generated video with one or more reference images that influence the output without forcing the first frame.

197* **[Video Extension](/developers/model-capabilities/video/extension)** — Continue an existing video from its last frame, combining the original and extension into one clip.197* **[Video Extension](/developers/model-capabilities/video/extension)** — Continue an existing video from its last frame, combining the original and extension into one clip.

198* **[Files API Integration](/developers/model-capabilities/imagine/files)** — Reference stored files as Imagine inputs by ID, persist generated assets to the Files API, and optionally create a permanent shareable public URL — all in a single request.198* **[Files API Integration](/developers/model-capabilities/imagine/files)** — Reference stored files as Imagine inputs by ID, persist generated assets to the Files API, and optionally create a permanent shareable public URL — all in a single request.

199 199 

42# 3. Animate the edited result into a video42# 3. Animate the edited result into a video

43vid = client.video.generate(43vid = client.video.generate(

44 prompt="A camera pulls back through the city",44 prompt="A camera pulls back through the city",

45 model="grok-imagine-video",45 model="grok-imagine-video-1.5",

46 duration=5,46 duration=5,

47 image_file_id=edit.file_output.file_id,47 image_file_id=edit.file_output.file_id,

48)48)

73```python customLanguage="pythonXAI"73```python customLanguage="pythonXAI"

74response = client.video.generate(74response = client.video.generate(

75 prompt="Pan across the scene as the sky darkens",75 prompt="Pan across the scene as the sky darkens",

76 model="grok-imagine-video",76 model="grok-imagine-video-1.5",

77 duration=5,77 duration=5,

78 image_file_id="file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",78 image_file_id="file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",

79)79)

86 -H "Authorization: Bearer $XAI_API_KEY" \86 -H "Authorization: Bearer $XAI_API_KEY" \

87 -H "Content-Type: application/json" \87 -H "Content-Type: application/json" \

88 -d '{88 -d '{

89 "model": "grok-imagine-video",89 "model": "grok-imagine-video-1.5",

90 "prompt": "Pan across the scene as the sky darkens",90 "prompt": "Pan across the scene as the sky darkens",

91 "duration": 5,91 "duration": 5,

92 "image": { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" }92 "image": { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" }

119```python customLanguage="pythonXAI"119```python customLanguage="pythonXAI"

120response = client.video.generate(120response = client.video.generate(

121 prompt="A woman in this dress walks down a city street at night",121 prompt="A woman in this dress walks down a city street at night",

122 model="grok-imagine-video",122 model="grok-imagine-video-1.5",

123 duration=5,123 duration=5,

124 reference_image_file_ids=[124 reference_image_file_ids=[

125 "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b", # subject125 "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b", # subject

134 -H "Authorization: Bearer $XAI_API_KEY" \134 -H "Authorization: Bearer $XAI_API_KEY" \

135 -H "Content-Type: application/json" \135 -H "Content-Type: application/json" \

136 -d '{136 -d '{

137 "model": "grok-imagine-video",137 "model": "grok-imagine-video-1.5",

138 "prompt": "A woman in this dress walks down a city street at night",138 "prompt": "A woman in this dress walks down a city street at night",

139 "duration": 5,139 "duration": 5,

140 "reference_images": [140 "reference_images": [

283# SDK handles polling automatically and returns the completed video.283# SDK handles polling automatically and returns the completed video.

284response = client.video.generate(284response = client.video.generate(

285 prompt="A ball bouncing slowly on a flat surface",285 prompt="A ball bouncing slowly on a flat surface",

286 model="grok-imagine-video",286 model="grok-imagine-video-1.5",

287 duration=5,287 duration=5,

288 storage_options={"filename": "bouncing-ball.mp4", "public_url": True},288 storage_options={"filename": "bouncing-ball.mp4", "public_url": True},

289)289)

299 -H "Authorization: Bearer $XAI_API_KEY" \299 -H "Authorization: Bearer $XAI_API_KEY" \

300 -H "Content-Type: application/json" \300 -H "Content-Type: application/json" \

301 -d '{301 -d '{

302 "model": "grok-imagine-video",302 "model": "grok-imagine-video-1.5",

303 "prompt": "A ball bouncing slowly on a flat surface",303 "prompt": "A ball bouncing slowly on a flat surface",

304 "duration": 5,304 "duration": 5,

305 "storage_options": {"filename": "bouncing-ball.mp4", "public_url": true}305 "storage_options": {"filename": "bouncing-ball.mp4", "public_url": true}

69import { experimental_generateVideo as generateVideo } from "ai";69import { experimental_generateVideo as generateVideo } from "ai";

70 70 

71const source = await generateVideo({71const source = await generateVideo({

72 model: xai.video("grok-imagine-video"),72 model: xai.video("grok-imagine-video-1.5"),

73 prompt: "A cat sitting on a sunlit windowsill, tail gently swishing.",73 prompt: "A cat sitting on a sunlit windowsill, tail gently swishing.",

74 duration: 5,74 duration: 5,

75 aspectRatio: "16:9",75 aspectRatio: "16:9",

2 2 

3# Video Generation3# Video Generation

4 4 

5Generate videos from text prompts with Grok video models. The API supports configurable duration, aspect ratio, and resolution, and the SDK handles asynchronous polling automatically.5Generate videos from text prompts with Grok video models. The API supports configurable duration, aspect ratio, and resolution, and the SDK handles asynchronous polling automatically. On `grok-imagine-video-1.5`, text-to-video supports native 1080p.

6 6 

7## Quick Start7## Quick Start

8 8 

16 16 

17response = client.video.generate(17response = client.video.generate(

18 prompt="A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",18 prompt="A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",

19 model="grok-imagine-video",19 model="grok-imagine-video-1.5",

20 duration=10,20 duration=10,

21 aspect_ratio="16:9",21 aspect_ratio="16:9",

22 resolution="720p",22 resolution="720p",

39 "https://api.x.ai/v1/videos/generations",39 "https://api.x.ai/v1/videos/generations",

40 headers=headers,40 headers=headers,

41 json={41 json={

42 "model": "grok-imagine-video",42 "model": "grok-imagine-video-1.5",

43 "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",43 "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",

44 "duration": 10,44 "duration": 10,

45 "aspect_ratio": "16:9",45 "aspect_ratio": "16:9",

70import { experimental_generateVideo as generateVideo } from "ai";70import { experimental_generateVideo as generateVideo } from "ai";

71 71 

72const result = await generateVideo({72const result = await generateVideo({

73 model: xai.video("grok-imagine-video"),73 model: xai.video("grok-imagine-video-1.5"),

74 prompt: "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",74 prompt: "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",

75 duration: 10,75 duration: 10,

76 aspectRatio: "16:9",76 aspectRatio: "16:9",

89 -H "Content-Type: application/json" \89 -H "Content-Type: application/json" \

90 -H "Authorization: Bearer $XAI_API_KEY" \90 -H "Authorization: Bearer $XAI_API_KEY" \

91 -d '{91 -d '{

92 "model": "grok-imagine-video",92 "model": "grok-imagine-video-1.5",

93 "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",93 "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",

94 "duration": 10,94 "duration": 10,

95 "aspect_ratio": "16:9",95 "aspect_ratio": "16:9",

116 116 

117* **Prompt complexity** — More detailed scenes require additional processing117* **Prompt complexity** — More detailed scenes require additional processing

118* **Duration** — Longer videos take more time to generate118* **Duration** — Longer videos take more time to generate

119* **Resolution** — Higher resolutions (720p vs 480p) increase processing time119* **Resolution** — Higher resolutions (1080p vs 480p) increase processing time

120* **Video editing** — Editing existing videos adds overhead compared to image-to-video or text-to-video120* **Video editing** — Editing existing videos adds overhead compared to image-to-video or text-to-video

121 121 

122## Video workflows122## Video workflows

123 123 

124Use the page that matches the kind of video output you want to create:124Use the page that matches the kind of video output you want to create:

125 125 

126* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts.

127* [Image-to-Video](/developers/model-capabilities/video/image-to-video) — Animate a still image.126* [Image-to-Video](/developers/model-capabilities/video/image-to-video) — Animate a still image.

128* [Video Editing](/developers/model-capabilities/video/editing) — Modify an existing video.127* [Video Editing](/developers/model-capabilities/video/editing) — Modify an existing video.

129* [Reference-to-Video](/developers/model-capabilities/video/reference-to-video) — Guide a generated video with one or more reference images.128* [Reference-to-Video](/developers/model-capabilities/video/reference-to-video) — Guide a generated video with one or more reference images.

147 -H "Content-Type: application/json" \146 -H "Content-Type: application/json" \

148 -H "Authorization: Bearer $XAI_API_KEY" \147 -H "Authorization: Bearer $XAI_API_KEY" \

149 -d '{148 -d '{

150 "model": "grok-imagine-video",149 "model": "grok-imagine-video-1.5",

151 "prompt": "A glowing crystal-powered rocket launching from Mars"150 "prompt": "A glowing crystal-powered rocket launching from Mars"

152 }'151 }'

153```152```

186 "duration": 8,185 "duration": 8,

187 "respect_moderation": true186 "respect_moderation": true

188 },187 },

189 "model": "grok-imagine-video"188 "model": "grok-imagine-video-1.5"

190}189}

191```190```

192 191 

194 193 

195## Configuration194## Configuration

196 195 

197The video generation API lets you control the output format of your generated videos. You can specify the duration, aspect ratio, and resolution to match your specific use case.196The video generation API lets you control the output format of your generated videos. You can specify the duration, aspect ratio, resolution, and (on reference-to-video) a preset voice to match your specific use case.

198 197 

199### Duration198### Duration

200 199 

223| `720p` | HD quality |222| `720p` | HD quality |

224| `480p` | Standard definition, faster processing (default) |223| `480p` | Standard definition, faster processing (default) |

225 224 

226> **Note:** `1080p` is only supported on `grok-imagine-video-1.5` for image-to-video generation.225**Note:** `1080p` is supported on `grok-imagine-video-1.5` for text-to-video and image-to-video. Reference-to-video is capped at 720p.

227 226 

228Video editing does not support custom `resolution`. The output resolution matches the input video's resolution, capped at 720p (e.g., a 1080p input will be downsized to 720p).227Video editing does not support custom `resolution`. The output resolution matches the input video's resolution, capped at 720p (e.g., a 1080p input will be downsized to 720p).

229 228 

229### Audio

230 

231> [!WARNING]

232>

233> Reference audio is currently only available in the **United States**, for trusted partners. .

234 

235On `grok-imagine-video-1.5`, [reference-to-video](/developers/model-capabilities/video/reference-to-video#reference-audio) can carry a voice via `reference_audios`. Voices come from the built-in roster and are named by `voice_id`; you cannot upload your own audio clips:

236 

237| Property | Description |

238|----------|-------------|

239| Source | A preset `voice_id` (e.g. `{"voice_id": "eve"}`), from the same roster as [Text to Speech](/developers/model-capabilities/audio/text-to-speech#voices). Identifiers are case-insensitive |

240| Limit | Max **3** voices per request |

241| Prompt | Reference voices by index: `<AUDIO_0>`, `<AUDIO_1>`, `<AUDIO_2>` |

242 

243Generated videos include an audio track by default.

244 

230### Example245### Example

231 246 

232```python customLanguage="pythonXAI"247```python customLanguage="pythonXAI"

237 252 

238response = client.video.generate(253response = client.video.generate(

239 prompt="Timelapse of a flower blooming in a sunlit garden",254 prompt="Timelapse of a flower blooming in a sunlit garden",

240 model="grok-imagine-video",255 model="grok-imagine-video-1.5",

241 duration=10,256 duration=10,

242 aspect_ratio="16:9",257 aspect_ratio="16:9",

243 resolution="720p",258 resolution="720p",

261 "https://api.x.ai/v1/videos/generations",276 "https://api.x.ai/v1/videos/generations",

262 headers=headers,277 headers=headers,

263 json={278 json={

264 "model": "grok-imagine-video",279 "model": "grok-imagine-video-1.5",

265 "prompt": "Timelapse of a flower blooming in a sunlit garden",280 "prompt": "Timelapse of a flower blooming in a sunlit garden",

266 "duration": 10,281 "duration": 10,

267 "aspect_ratio": "16:9",282 "aspect_ratio": "16:9",

292import { experimental_generateVideo as generateVideo } from "ai";307import { experimental_generateVideo as generateVideo } from "ai";

293 308 

294const result = await generateVideo({309const result = await generateVideo({

295 model: xai.video("grok-imagine-video"),310 model: xai.video("grok-imagine-video-1.5"),

296 prompt: "Timelapse of a flower blooming in a sunlit garden",311 prompt: "Timelapse of a flower blooming in a sunlit garden",

297 duration: 10,312 duration: 10,

298 aspectRatio: "16:9",313 aspectRatio: "16:9",

311 -H "Content-Type: application/json" \326 -H "Content-Type: application/json" \

312 -H "Authorization: Bearer $XAI_API_KEY" \327 -H "Authorization: Bearer $XAI_API_KEY" \

313 -d '{328 -d '{

314 "model": "grok-imagine-video",329 "model": "grok-imagine-video-1.5",

315 "prompt": "Timelapse of a flower blooming in a sunlit garden",330 "prompt": "Timelapse of a flower blooming in a sunlit garden",

316 "duration": 10,331 "duration": 10,

317 "aspect_ratio": "16:9",332 "aspect_ratio": "16:9",

342|------|-----------------|--------------|-------------|357|------|-----------------|--------------|-------------|

343| Text-to-video | `prompt` only | `prompt: "..."` | Generates video from a text prompt alone. |358| Text-to-video | `prompt` only | `prompt: "..."` | Generates video from a text prompt alone. |

344| Image-to-video | `prompt` + `image` | `prompt: { image, text }` | Generates video with the provided image as the starting frame. |359| Image-to-video | `prompt` + `image` | `prompt: { image, text }` | Generates video with the provided image as the starting frame. |

345| Reference-to-video | `prompt` + `reference_images` | `prompt: "..."` + `providerOptions.xai.{ mode: "reference-to-video", referenceImageUrls }` | Generates video guided by one or more reference images. |360| Reference-to-video | `prompt` + `reference_images` or `reference_audios` | `prompt: "..."` + `providerOptions.xai.{ mode: "reference-to-video", referenceImageUrls }` | Generates video guided by reference images and/or a preset voice on `grok-imagine-video-1.5`. |

346| Edit-video | `/v1/videos/edits` + `video` | `prompt: "..."` + `providerOptions.xai.{ mode: "edit-video", videoUrl }` | Modifies an existing video based on the prompt. |361| Edit-video | `/v1/videos/edits` + `video` | `prompt: "..."` + `providerOptions.xai.{ mode: "edit-video", videoUrl }` | Modifies an existing video based on the prompt. |

347| Extend-video | `/v1/videos/extensions` + `video` | `prompt: "..."` + `providerOptions.xai.{ mode: "extend-video", videoUrl }` | Extends an existing video from its last frame. |362| Extend-video | `/v1/videos/extensions` + `video` | `prompt: "..."` + `providerOptions.xai.{ mode: "extend-video", videoUrl }` | Extends an existing video from its last frame. |

348 363 

371 386 

372response = client.video.generate(387response = client.video.generate(

373 prompt="Epic cinematic drone shot flying through mountain peaks",388 prompt="Epic cinematic drone shot flying through mountain peaks",

374 model="grok-imagine-video",389 model="grok-imagine-video-1.5",

375 duration=15,390 duration=15,

376 timeout=timedelta(minutes=15), # Wait up to 15 minutes391 timeout=timedelta(minutes=15), # Wait up to 15 minutes

377 interval=timedelta(seconds=5), # Check every 5 seconds392 interval=timedelta(seconds=5), # Check every 5 seconds

385import { experimental_generateVideo as generateVideo } from "ai";400import { experimental_generateVideo as generateVideo } from "ai";

386 401 

387const result = await generateVideo({402const result = await generateVideo({

388 model: xai.video("grok-imagine-video"),403 model: xai.video("grok-imagine-video-1.5"),

389 prompt: "Epic cinematic drone shot flying through mountain peaks",404 prompt: "Epic cinematic drone shot flying through mountain peaks",

390 duration: 15,405 duration: 15,

391 providerOptions: {406 providerOptions: {

419# Start the generation request434# Start the generation request

420start_response = client.video.start(435start_response = client.video.start(

421 prompt="A cat lounging in a sunbeam, tail gently swishing",436 prompt="A cat lounging in a sunbeam, tail gently swishing",

422 model="grok-imagine-video",437 model="grok-imagine-video-1.5",

423 duration=5,438 duration=5,

424)439)

425 440 

458 "https://api.x.ai/v1/videos/generations",473 "https://api.x.ai/v1/videos/generations",

459 headers=headers,474 headers=headers,

460 json={475 json={

461 "model": "grok-imagine-video",476 "model": "grok-imagine-video-1.5",

462 "prompt": "A cat lounging in a sunbeam, tail gently swishing",477 "prompt": "A cat lounging in a sunbeam, tail gently swishing",

463 "duration": 5,478 "duration": 5,

464 },479 },

498 "Authorization": `Bearer ${process.env.XAI_API_KEY}`,513 "Authorization": `Bearer ${process.env.XAI_API_KEY}`,

499 },514 },

500 body: JSON.stringify({515 body: JSON.stringify({

501 model: "grok-imagine-video",516 model: "grok-imagine-video-1.5",

502 prompt: "A cat lounging in a sunbeam, tail gently swishing",517 prompt: "A cat lounging in a sunbeam, tail gently swishing",

503 duration: 5,518 duration: 5,

504 }),519 }),

537 -H "Content-Type: application/json" \552 -H "Content-Type: application/json" \

538 -H "Authorization: Bearer $XAI_API_KEY" \553 -H "Authorization: Bearer $XAI_API_KEY" \

539 -d '{554 -d '{

540 "model": "grok-imagine-video",555 "model": "grok-imagine-video-1.5",

541 "prompt": "A cat lounging in a sunbeam, tail gently swishing",556 "prompt": "A cat lounging in a sunbeam, tail gently swishing",

542 "duration": 5557 "duration": 5

543 }' | jq -r '.request_id')558 }' | jq -r '.request_id')

584try:599try:

585 response = client.video.generate(600 response = client.video.generate(

586 prompt="A cat lounging in a sunbeam, tail gently swishing",601 prompt="A cat lounging in a sunbeam, tail gently swishing",

587 model="grok-imagine-video",602 model="grok-imagine-video-1.5",

588 duration=5,603 duration=5,

589 )604 )

590 print(response.url)605 print(response.url)

636try:651try:

637 response = client.video.generate(652 response = client.video.generate(

638 prompt="A cat lounging in a sunbeam, tail gently swishing",653 prompt="A cat lounging in a sunbeam, tail gently swishing",

639 model="grok-imagine-video",654 model="grok-imagine-video-1.5",

640 duration=5,655 duration=5,

641 )656 )

642 print(response.url)657 print(response.url)

662 677 

663```javascript customLanguage="javascriptAISDK"678```javascript customLanguage="javascriptAISDK"

664const result = await generateVideo({679const result = await generateVideo({

665 model: xai.video("grok-imagine-video"),680 model: xai.video("grok-imagine-video-1.5"),

666 prompt: "A futuristic city skyline at dusk",681 prompt: "A futuristic city skyline at dusk",

667 duration: 5,682 duration: 5,

668});683});

691 tasks = [706 tasks = [

692 client.video.generate(707 client.video.generate(

693 prompt=prompt,708 prompt=prompt,

694 model="grok-imagine-video",709 model="grok-imagine-video-1.5",

695 duration=5,710 duration=5,

696 )711 )

697 for prompt in prompts712 for prompt in prompts

2 2 

3# Image-to-Video3# Image-to-Video

4 4 

5Transform a still image into a video by providing a source image along with your prompt. The model animates the image content based on your instructions.5Transform a still image into a video by providing a source image along with an optional prompt. The model animates the image content based on your instructions. On `grok-imagine-video-1.5`, image-to-video supports native 1080p.

6 6 

7You can provide the source image as:7You can provide the source image as:

8 8 

18 18 

19* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts19* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts

20* [Reference-to-Video](/developers/model-capabilities/video/reference-to-video) — Guide a video with reference images20* [Reference-to-Video](/developers/model-capabilities/video/reference-to-video) — Guide a video with reference images

21* [Model page: grok-imagine-video-1.5](/developers/models/grok-imagine-video-1.5)

22* [Videos API](/developers/rest-api-reference/inference/videos) — Video generation endpoints

21* [Video Editing](/developers/model-capabilities/video/editing) — Edit existing videos23* [Video Editing](/developers/model-capabilities/video/editing) — Edit existing videos

22* [API Reference](/developers/rest-api-reference) — Full endpoint documentation24* [API Reference](/developers/rest-api-reference) — Full endpoint documentation

23* [Imagine API Landing Page](https://x.ai/api/imagine) — Showcase of the Imagine API in action25* [Imagine API Landing Page](https://x.ai/api/imagine) — Showcase of the Imagine API in action

2 2 

3# Reference-to-Video3# Reference-to-Video

4 4 

5Provide one or more reference images to incorporate specific people, objects, clothing, or other visual elements into the generated video. The model uses the reference images as a visual guide, producing a video that features the content from those images. This is useful for virtual try-on, product placement, and character-consistent storytelling.5Provide reference images, a preset voice, or both to guide the generated video. Images incorporate specific people, objects, clothing, or other visual elements without locking the first frame (unlike [image-to-video](/developers/model-capabilities/video/image-to-video)). This is useful for virtual try-on, product placement, character-consistent storytelling, and voice identity. On `grok-imagine-video-1.5`, you can also pick the voice your subject speaks in (see [Reference audio](#reference-audio)).

6 

7Unlike [image-to-video](/developers/model-capabilities/video/image-to-video), where the source image becomes the starting frame, reference images influence what appears in the video without locking in the first frame.

8 6 

9Each reference image can be provided as a public HTTPS URL, a base64-encoded data URI, or a `file_id` from the [Files API](/developers/files) — and you can mix kinds within a single request. See [Imagine → Files API Integration](/developers/model-capabilities/imagine/files/inputs) for `file_id` details and examples.7Each reference image can be provided as a public HTTPS URL, a base64-encoded data URI, or a `file_id` from the [Files API](/developers/files) — and you can mix kinds within a single request. See [Imagine → Files API Integration](/developers/model-capabilities/imagine/files/inputs) for `file_id` details and examples.

10 8 

20 18 

21response = client.video.generate(19response = client.video.generate(

22 prompt="slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",20 prompt="slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",

23 model="grok-imagine-video",21 model="grok-imagine-video-1.5",

24 reference_image_urls=[22 reference_image_urls=[

25 "<IMAGE_URL_1>",23 "<IMAGE_URL_1>",

26 "<IMAGE_URL_2>",24 "<IMAGE_URL_2>",

48 "https://api.x.ai/v1/videos/generations",46 "https://api.x.ai/v1/videos/generations",

49 headers=headers,47 headers=headers,

50 json={48 json={

51 "model": "grok-imagine-video",49 "model": "grok-imagine-video-1.5",

52 "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",50 "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",

53 "reference_images": [51 "reference_images": [

54 {"url": "<IMAGE_URL_1>"},52 {"url": "<IMAGE_URL_1>"},

83import { experimental_generateVideo as generateVideo } from "ai";81import { experimental_generateVideo as generateVideo } from "ai";

84 82 

85const result = await generateVideo({83const result = await generateVideo({

86 model: xai.video("grok-imagine-video"),84 model: xai.video("grok-imagine-video-1.5"),

87 prompt: "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",85 prompt: "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",

88 duration: 10,86 duration: 10,

89 aspectRatio: "16:9",87 aspectRatio: "16:9",

111 -H "Content-Type: application/json" \109 -H "Content-Type: application/json" \

112 -H "Authorization: Bearer $XAI_API_KEY" \110 -H "Authorization: Bearer $XAI_API_KEY" \

113 -d '{111 -d '{

114 "model": "grok-imagine-video",112 "model": "grok-imagine-video-1.5",

115 "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",113 "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",

116 "reference_images": [114 "reference_images": [

117 {"url": "<IMAGE_URL_1>"},115 {"url": "<IMAGE_URL_1>"},

139done137done

140```138```

141 139 

140## Reference audio

141 

142> [!WARNING]

143>

144> Reference audio is currently only available in the **United States**, for trusted partners. .

145 

146On `grok-imagine-video-1.5`, give your subject a voice by passing up to **3** preset voices with `reference_audios`. Each entry names a voice by `voice_id`, drawn from the same built-in roster as [Text to Speech](/developers/model-capabilities/audio/text-to-speech#voices), so `{"voice_id": "eve"}` speaks in Eve's voice. Identifiers are case-insensitive; an unknown one returns `400` with the list of available voices. You can hear every voice in the [flagship voices announcement](https://x.ai/news/new-flagship-voices).

147 

148`reference_audios` accepts preset voices only; you cannot upload your own audio clips. Use a voice alongside reference images or on its own, and tag voices in the prompt as `<AUDIO_0>`, `<AUDIO_1>`, and `<AUDIO_2>` (with `<IMAGE_0>`… when you also pass images).

149 

150```python customLanguage="pythonRequests"

151import os

152import time

153import requests

154 

155headers = {

156 "Content-Type": "application/json",

157 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",

158}

159 

160response = requests.post(

161 "https://api.x.ai/v1/videos/generations",

162 headers=headers,

163 json={

164 "model": "grok-imagine-video-1.5",

165 "prompt": "The person from <IMAGE_1> speaks to camera with the voice from <AUDIO_0>.",

166 "reference_images": [{"url": "<IMAGE_URL_1>"}],

167 "reference_audios": [{"voice_id": "eve"}],

168 "duration": 8,

169 "aspect_ratio": "9:16",

170 "resolution": "720p",

171 },

172)

173 

174request_id = response.json()["request_id"]

175 

176while True:

177 result = requests.get(

178 f"https://api.x.ai/v1/videos/{request_id}",

179 headers={"Authorization": headers["Authorization"]},

180 )

181 data = result.json()

182 if data["status"] == "done":

183 print(data["video"]["url"])

184 break

185 elif data["status"] == "expired":

186 print("Request expired")

187 break

188 time.sleep(5)

189```

190 

191```bash

192REQUEST_ID=$(curl -s -X POST https://api.x.ai/v1/videos/generations \

193 -H "Content-Type: application/json" \

194 -H "Authorization: Bearer $XAI_API_KEY" \

195 -d '{

196 "model": "grok-imagine-video-1.5",

197 "prompt": "The person from <IMAGE_1> speaks to camera with the voice from <AUDIO_0>.",

198 "reference_images": [{"url": "<IMAGE_URL_1>"}],

199 "reference_audios": [{"voice_id": "eve"}],

200 "duration": 8,

201 "aspect_ratio": "9:16",

202 "resolution": "720p"

203 }' | jq -r '.request_id')

204 

205while true; do

206 RESULT=$(curl -s https://api.x.ai/v1/videos/$REQUEST_ID \

207 -H "Authorization: Bearer $XAI_API_KEY")

208 STATUS=$(echo "$RESULT" | jq -r '.status')

209 if [ "$STATUS" = "done" ]; then

210 echo "$RESULT" | jq -r '.video.url'

211 break

212 elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ]; then

213 echo "Request $STATUS"; echo "$RESULT" | jq .

214 break

215 fi

216 sleep 5

217done

218```

219 

142## Related220## Related

143 221 

144* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts222* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts

39| grok-4.20-0309-non-reasoning | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |39| grok-4.20-0309-non-reasoning | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |

40| grok-build-0.1 | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |40| grok-build-0.1 | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |

41| grok-4.20-multi-agent-0309 | T0: 9, T1: 12, T2: 18, T3: 31, T4: 56 | T0: 2.5M, T1: 3.7M, T2: 6.2M, T3: 11M, T4: 21M |41| grok-4.20-multi-agent-0309 | T0: 9, T1: 12, T2: 18, T3: 31, T4: 56 | T0: 2.5M, T1: 3.7M, T2: 6.2M, T3: 11M, T4: 21M |

42| grok-imagine-image | 5 | — |

43| grok-imagine-image-quality | 5 | — |42| grok-imagine-image-quality | 5 | — |

44| grok-imagine-video | 10 | — |43| grok-imagine-image | 5 | — |

45| grok-imagine-video-1.5 | 10 | — |44| grok-imagine-video-1.5 | 10 | — |

45| grok-imagine-video | 10 | — |

46 46 

47### What counts toward TPM47### What counts toward TPM

48 48 

459 459 

460 * `id` (string, required) — Model ID.460 * `id` (string, required) — Model ID.

461 461 

462 * `input_modalities` (array\<string>, required) — The input modalities supported by the model (e.g. "text", "image").462 * `input_modalities` (array\<string>, required) — The input modalities supported by the model (e.g. "text", "image";

463 "audio" for models accepting reference audio).

463 464 

464 * `object` (string, required) — The object type, which is always \`"model"\`.465 * `object` (string, required) — The object type, which is always \`"model"\`.

465 466 

514 515 

515* `id` (string, required) — Model ID.516* `id` (string, required) — Model ID.

516 517 

517* `input_modalities` (array\<string>, required) — The input modalities supported by the model (e.g. "text", "image").518* `input_modalities` (array\<string>, required) — The input modalities supported by the model (e.g. "text", "image";

519 "audio" for models accepting reference audio).

518 520 

519* `object` (string, required) — The object type, which is always \`"model"\`.521* `object` (string, required) — The object type, which is always \`"model"\`.

520 522 

34 reference-to-video (R2V). Optional for image-to-video (I2V) — when34 reference-to-video (R2V). Optional for image-to-video (I2V) — when

35 omitted, the model generates a video from the image alone.35 omitted, the model generates a video from the image alone.

36 36 

37* `reference_audios` (array\<object>) — Optional reference audio clips (voice identity) for reference-to-video37* `reference_audios` (array\<object>) — Optional reference audio (voice identity) for reference-to-video

38 generation. Only supported by select video models; at most 3 clips.38 generation. Each entry selects a first-party preset voice via

39 \`voice\_id\`. Only supported by select video models; at most 3 entries.

39 May be provided without \`reference\_images\` (audio-only40 May be provided without \`reference\_images\` (audio-only

40 reference-to-video) — at least one reference of either kind selects41 reference-to-video) — at least one reference of either kind selects

41 the reference-to-video mode.42 the reference-to-video mode.

42 43 

43 * `url` (string, required) — Base64-encoded audio data URL (e.g. "data:audio/wav;base64,...") or an44 * `voice_id` (string, required) — Identifier of a first-party preset voice (e.g. "ara"; same voice

44 http(s) URL to a downloadable audio clip.45 identifiers as the TTS API), resolved server-side to a curated

46 reference clip from the model's voice-preset catalog.

45 47 

46* `reference_images` (array\<object>) — Optional reference images for reference-to-video (R2V) generation.48* `reference_images` (array\<object>) — Optional reference images for reference-to-video (R2V) generation.

47 When provided generates video using these images49 When provided generates video using these images

78 -H "Content-Type: application/json" \80 -H "Content-Type: application/json" \

79 -H "Authorization: Bearer $XAI_API_KEY" \81 -H "Authorization: Bearer $XAI_API_KEY" \

80 -d '{82 -d '{

81 "model": "grok-imagine-video",83 "model": "grok-imagine-video-1.5",

82 "prompt": "A serene lake at sunrise with mist rolling over the water"84 "prompt": "A serene lake at sunrise with mist rolling over the water"

83 }'85 }'

84```86```

91 "Content-Type": "application/json",93 "Content-Type": "application/json",

92 },94 },

93 body: JSON.stringify({95 body: JSON.stringify({

94 model: "grok-imagine-video",96 model: "grok-imagine-video-1.5",

95 prompt: "A serene lake at sunrise with mist rolling over the water",97 prompt: "A serene lake at sunrise with mist rolling over the water",

96 }),98 }),

97});99});

112 "Content-Type": "application/json",114 "Content-Type": "application/json",

113 },115 },

114 json={116 json={

115 "model": "grok-imagine-video",117 "model": "grok-imagine-video-1.5",

116 "prompt": "A serene lake at sunrise with mist rolling over the water",118 "prompt": "A serene lake at sunrise with mist rolling over the water",

117 },119 },

118)120)