xAI Video

Create, edit, and extend Grok Imagine videos with asynchronous xAI-compatible endpoints.

Endpoints

POST /v1/videos/generations
POST /v1/videos/edits
POST /v1/videos/extensions
Authorization: Bearer $API_KEY
Content-Type: application/json

These endpoints accept xAI-compatible JSON plus the platform callback_url field. They return immediately after the upstream accepts the task. Save the rewritten request_id and query it through GET /v1/tasks/{taskId}.

Generate video

POST /v1/videos/generations supports text-to-video, image-to-video, and model-supported reference generation.

Field	Type	Required	Description
`model`	string	Yes	Complete public video model ID.
`prompt`	string	Required by text generation and model rules	Generation instruction.
`image`	object	No	One image using `url` or a base64 data URI; `file_id` is rejected.
`reference_images`	array	No	Model-supported reference images using `url` or a base64 data URI; `file_id` is rejected.
`reference_audios`	array	No	Up to three supported references using `url` or `voice_id`.
`resolution`	`480p`, `720p`, or `1080p`	No	Model-dependent output resolution; admission default is `480p`.
`aspect_ratio`	string	No	One of `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`, or `5:2`.
`duration`	integer or integer string	No	Requested seconds in the range 1–15; defaults to `8`.
`seconds`	integer or integer string	No	Compatible alias used when `duration` is absent.
`user`	string	No	Stable end-user identifier.
`callback_url`	string	No	Public terminal callback URL.

curl "http://127.0.0.1:11113/v1/videos/generations" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
  "model": "xai/grok-imagine-video-1.5",
  "prompt": "A paper airplane flying through clouds",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration": 8,
  "callback_url": "https://example.com/hooks/video?token=unguessable"
}'

For image-to-video, add one image object. The platform does not proxy the xAI Files API, so file_id inputs are rejected; use a URL or base64 data URI instead.

The mode follows the request shape: reference arrays select reference-to-video; last_frame, keyframes, or an image combined with references select first-last-frame; an image alone selects image-to-video; otherwise the request is text-to-video. Pinned frames (last_frame, keyframes) are available on Grok Imagine Video 1.5 only, and reference-to-video and first-last-frame can be combined when the model supports both.

Model	Modes	Resolutions
`grok-imagine-video`	text, image, reference, edit, extend	480p, 720p
`grok-imagine-video-1.5`	text, image, first-last-frame, reference	480p, 720p, 1080p
`grok-imagine-video-1.5-lite`	text, image	480p, 720p, 1080p

Edit video

POST /v1/videos/edits requires model, a non-empty prompt, and a video object. The video can use a public MP4 URL or an MP4 data URI; user is optional.

{
  "model": "xai/grok-imagine-video",
  "prompt": "Change the lighting to sunset",
  "video": { "url": "https://example.com/source.mp4" },
  "callback_url": "https://example.com/hooks/video?token=unguessable"
}

The source video is estimated at the supported input upper bound for admission, then final billing uses the terminal task usage and result.

Extend video

POST /v1/videos/extensions also requires model, prompt, and video. duration is the new segment length, accepts 2–10 seconds, and defaults to 6.

{
  "model": "xai/grok-imagine-video",
  "prompt": "Continue into a starry night",
  "video": { "url": "https://example.com/source.mp4" },
  "duration": 6
}

Editing and extension inherit source-dependent output properties. Send only fields supported by the selected model.

Create response

The upstream request_id is replaced with a platform task ID before the response reaches you.

{
  "request_id": "9dcf8ab2-c4b7-42be-a516-597223897b99"
}

Never use this ID against xAI directly. It identifies the platform task and is scoped to the authenticated wallet.

Task response

curl "http://127.0.0.1:11113/v1/tasks/9dcf8ab2-c4b7-42be-a516-597223897b99" -H "Authorization: Bearer $API_KEY"

{
  "request_id": "9dcf8ab2-c4b7-42be-a516-597223897b99",
  "status": "done",
  "progress": 100,
  "model": "xai/grok-imagine-video-1.5",
  "video": {
    "url": "https://vidgen.example/video.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "usage": {
    "cost_in_usd_ticks": 6400000000
  }
}

Common xAI statuses are pending, done, failed, and expired. Video results are temporarily retained for 48 hours and automatically deleted upon expiration—download and transfer any files you need to retain immediately after completion.

Restrictions

Non-null output and storage_options return 400 stateful_not_supported; the platform does not create or own upstream files.
image, last_frame, reference_images[].file_id, keyframes[].image.file_id, and the edit/extension video.file_id return 400 stateful_not_supported; these references depend on the upstream account's Files API, so use a URL or base64 data URI instead.
provider, routing, route, and paid service-tier selections are rejected.
Video requests do not support Idempotency-Key.
Body size defaults to 50 MiB. Data URIs are forwarded unchanged but replaced by placeholders in stored logs.

See Tasks and callbacks for polling, callback delivery, ownership, and retry behavior.