Set duration on Imagine API videos

Pin clip length when you generate a video through the Imagine API so you pay for the seconds you need and match the cut you already planned. Official Video Generation documents the duration parameter with an allowed range of 1–15 seconds. The REST reference notes a default of 8 seconds when you omit it, and also accepts seconds for OpenAI-compatible clients. Video editing does not support custom duration — an edited clip keeps the source length (capped at 8.7 seconds). Create a key and load credits at console.x.ai; pricing is per second on grok-imagine-video and grok-imagine-video-1.5.

What you need

An XAI_API_KEY with Console balance, a text-to-video or image-to-video request you already know how to send, and a target length in whole seconds inside 1–15. Use this job together with Generate a video from text with the Imagine API or Animate a still with the Imagine API. Longer clips cost more and usually take longer to finish.

Pin the length

1. Export the key locally and keep it out of chat logs and public repos:

export XAI_API_KEY="your_api_key"

2. Pass duration on the SDK call (example at 6 seconds):

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="Timelapse of a flower blooming in a sunlit garden",
    model="grok-imagine-video-1.5",
    duration=6,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)
print(response.duration)

3. Or set it on the REST body:

curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Timelapse of a flower blooming in a sunlit garden",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

4. Poll until status is done, then confirm video.duration matches the seconds you asked for before you bill a longer retry.
5. Pass resolution on the same request when sharpness is already fixed for the placement, then edit a finished clip with Edit a video with the Imagine API if a region still needs a prompt change.

After the generate

If the action feels rushed at 6 seconds, raise duration in small steps rather than jumping straight to 15. If the action is finished early, shorten the next run instead of trimming in an editor that still costs you the full billed seconds. Video editing keeps source duration, so lock length on the generation call when the cut matters. For silent exports at the same length, pass generate_audio=false on the generation request.

Pitfalls

Omitting duration when you meant a short cut leaves you on the 8-second default and bills accordingly. Values outside 1–15 return an invalid-argument failure. Expecting /v1/videos/edits to honor a new duration wastes a run — edit keeps the original length. Longer durations and higher resolutions increase wall time as well as cost; bumping both at once on a first draft is an expensive way to learn. Pasting keys into tickets or committing them to git forces a rotate.