Set aspect ratio on Imagine video generation

Pass aspect_ratio on POST https://api.x.ai/v1/videos/generations (or the matching SDK argument). Default is 16:9. Allowed values:

Ratio	Typical use
1:1	Social square, thumbnails
16:9 / 9:16	Widescreen, stories / mobile
4:3 / 3:4	Presentations, portraits
3:2 / 2:3	Photography frames

Text-to-video

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

import os
from xai_sdk import Client

client = 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=8,
    aspect_ratio="9:16",
    resolution="720p",
)
print(response.url)

import { xai } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const result = await generateVideo({
  model: xai.video("grok-imagine-video-1.5"),
  prompt: "Timelapse of a flower blooming in a sunlit garden",
  duration: 8,
  aspectRatio: "9:16",
  providerOptions: { xai: { resolution: "720p" } },
});
console.log(result.providerMetadata?.xai?.videoUrl);

Image-to-video default vs override

With an image input and no aspect_ratio, the output keeps the source image's ratio. If you set aspect_ratio, the API stretches the still to that frame — useful for forcing a story crop, easy to distort if the still and target diverge.

Modes that ignore custom ratio

• Video editing (/v1/videos/edits): output matches the input video's aspect ratio.
• Video extension keeps the source clip's geometry the same way.

Resolution and duration still follow their own tables (480p / 720p / 1080p on generation; duration 1–15 s). For Full HD, see Generate 1080p Imagine video.

Pitfalls

• An unsupported ratio string returns invalid_argument on the failed job (or a sync validation error before a request_id exists).
• Stretching a tall product still into 16:9 will letterbox-warp — crop the still first when fidelity matters.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.