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`/data URI or a compatible `file_id`.
`reference_images`	array	No	Model-supported reference images using `url` or `file_id`.
`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`, or `2:3`.
`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. Reference arrays select reference-to-video behavior when supported by the model. The platform does not expose an xAI Files API, so URL or data-URI inputs are the portable choice; a file_id is useful only when it already exists in the compatible upstream context.

Edit video

POST /v1/videos/edits requires model, a non-empty prompt, and a video object. The video can use a public MP4 URL, MP4 data URI, or compatible file_id; 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. Result URLs are passed through and are not downloaded or proxied by the platform, so copy files you need to retain.

Restrictions

Non-null output and storage_options return 400 stateful_not_supported; the platform does not create or own upstream files.
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.