Endpoint /v1/videos/generations: Your First Video

Updated November 3, 2026 based on xAI video documentation: three video models are available (grok-imagine-video-1.5, its -lite version, and grok-imagine-video), resolution goes up to 1080p on the 1.5 models, videos have an audio track by default (generate_audio), rate limits count in requests per second, and the size parameter presented by the old version does not appear in the API reference. Sources: Video Generation · Pricing.

Generate a Video from Text

xAI’s API exposes a dedicated video endpoint, POST /v1/videos/generations, which transforms a written description into an animated sequence using one of the three Grok Imagine Video models. Think of it as a studio on demand: you describe a scene, the model brings it to motion, and you retrieve an MP4 file ready for editing. Promotional clips, concept visualizations, illustrative animations—all these use cases go through this same endpoint, so we’ll dissect it first.

The example above gives you an idea of the expected output. Before writing your first request, keep in mind the four boundaries that frame everything you produce with these models.

Request Structure

The request body is a JSON object of reassuring simplicity. You declare the model, write your prompt, and frame the result with three formatting parameters.

{
  "model": "grok-imagine-video",
  "prompt": "A dolphin jumping in a sunset",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

Here is the exact meaning of each field:

• model: grok-imagine-video-1.5, the newest, its economy version grok-imagine-video-1.5-lite, recommended by xAI for simple videos, or grok-imagine-video, the previous generation, still used in this course’s examples
• prompt: your text description of the desired scene
• duration: duration in seconds, between 1 and 15 (8 by default)
• aspect_ratio: image ratio (16:9 by default, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
• resolution: 480p (default), 720p, or 1080p—the latter rendered natively by grok-imagine-video-1.5 in text-to-video and image-to-video, obtained by upsampling 720p on the -lite version, and absent from grok-imagine-video, which stops at 720p

Two points deserve emphasis right now. The grok-imagine-video model costs $0.050 per second of generated video ($0.08 for grok-imagine-video-1.5, $0.02 for its -lite version, as of November 3, 2026): a five-second sequence therefore costs you $0.25 with the first one, regardless of how many attempts got you there. And the rate limit counts in requests per second, depending on your team’s tier: 10 at the entry tier for video models, a comfortable margin for normal use, which becomes a constraint when you launch massive batches.

Most importantly, generation is asynchronous. Your POST call does not return a video: it returns a request_id, and it’s then up to you to poll the status until the file is ready. This polling mechanism is the subject of a full lesson later in the course; for now, just remember that the immediate response is an acknowledgment, not a result.

A First End-to-End Call

Let’s move to practice with curl. The following request orders a five-second sequence in 720p, landscape format.

curl -X POST "https://api.x.ai/v1/videos/generations" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A cat playing with a ball of yarn in a bright living room",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

The response fits on one line:

{
  "request_id": "vid_abc123def456"
}

Keep this identifier safe. It’s your only way to retrieve the video once generation is complete, and an application that loses it has paid for a generation it will never retrieve. In a real service, you log it before even starting the polling.

Audio, by Default

A generated video includes an audio track by default—with, on grok-imagine-video-1.5 and its -lite version, speech synchronized to lip movement. For a silent video, intended for example as a site background or for editing where you will add your own music, add "generate_audio": false to the request.

To frame the output, however, the API only knows the ratio (aspect_ratio) and the definition (resolution): the API reference provides no pixel size parameter. In image-to-video, the output ratio always follows that of the source image.

Key Takeaways

• The endpoint is POST /v1/videos/generations, with grok-imagine-video-1.5, its -lite version, or grok-imagine-video
• Duration ranges from 1 to 15 seconds (8 by default), resolution from 480p to 1080p (720p max with grok-imagine-video)
• Price counts per generated second: $0.020 (-lite), $0.050 (grok-imagine-video), or $0.080 (grok-imagine-video-1.5)
• Generation is asynchronous: you receive a request_id to poll afterward
• Nine aspect ratios are available to adapt to all formats
• An audio track is generated by default; "generate_audio": false gives a silent video