Set resolution on Imagine API videos

Pin 480p, 720p, or 1080p when you generate a video through the Imagine API so the output matches the sharpness you need for a draft, a web embed, or a Full HD cut. Official Video Generation documents the resolution parameter on POST https://api.x.ai/v1/videos/generations. When you omit it, the default is 480p. On grok-imagine-video-1.5, text-to-video and image-to-video accept native 1080p; reference-to-video stays capped at 720p. Video editing does not take a custom resolution — the edited clip matches the source, capped at 720p. Create a key and load credits at console.x.ai before you bill a sharper run.

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 decision on whether this placement needs more than the 480p default. Use this job together with Generate a video from text with the Imagine API or Animate a still with the Imagine API. Higher resolutions usually take longer to finish and cost more wall time on the same duration.

Choose and set resolution

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

export XAI_API_KEY="your_api_key"

2. Pass resolution on the SDK call (example at 720p):

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=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

3. Or set it on the REST body, including 1080p for text-to-video and image-to-video on grok-imagine-video-1.5:

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": 10,
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }'

4. Poll until status is done, download the temporary URL promptly, and confirm the clip looks sharp enough for the placement before you spend another run.
5. Keep reference-to-video at 480p or 720p — asking for 1080p on that mode fails with a precondition error. For a dedicated Full HD walkthrough, see Generate 1080p Imagine video with the API.

After the generate

Draft at 480p when you are still iterating on prompt and motion, then raise resolution once the shot is locked. Pair resolution with Set duration on Imagine API videos so you do not bump both length and sharpness on a first draft. If a region of the finished clip is wrong, edit from the output URL with Edit a video with the Imagine API, remembering edit output stays at most 720p.

Pitfalls

Leaving resolution unset leaves you on 480p when the placement already needed HD. Asking for 1080p on reference-to-video or on a model that cannot process it returns failed_precondition. Expecting /v1/videos/edits to honor a new resolution wastes a run — edit matches the source and caps at 720p. Bumping resolution and duration together on an untested prompt is an expensive way to learn. Pasting keys into tickets or committing them to git forces a rotate.