Create xAI video

This endpoint is compatible with xAI's video generation API. If you already have xAI code, point base_url at this site — the request body and response shape match what your client sends today.

Supported models#

⚠️ 1080p is supported only on x-ai/grok-imagine-video-1.5. Requesting it on x-ai/grok-imagine-video returns a 400 rather than a silent downgrade — with a downgrade, the mismatch would only surface after the task completed and was billed.

Exact value domains are also available from supported_parameters in GET /v1/models, which matches what is actually accepted.

Four generation modes#

The mode is determined by the material supplied; no separate declaration is needed:

prompt is optional when any material is supplied. This is the inverse of the MiniMax video endpoint, so no placeholder prompt is required when migrating from it. Supplying neither prompt nor material returns a 400.

Parameter behaviour#

duration defaults to 8 seconds#

This is the upstream default. When omitted, the output is 8 seconds long and billed as 8 seconds.

The duration cap on x-ai/grok-imagine-video varies by mode#

This model supports up to 15 seconds for plain text- and image-to-video. Once the request includes reference_images or last_frame, the cap narrows to 10 seconds.

Exceeding the cap returns a synchronous 400 at submit time, not a late failure. x-ai/grok-imagine-video-1.5 has no such narrowing and supports 15 seconds across all four modes.

For image-to-video, the source image determines output size#

In this mode aspect_ratio and resolution do not determine the output size — the aspect ratio always follows the supplied image. A 3:2 image yields a 3:2 video; specifying aspect_ratio: "16:9" does not change that.

Billing is unaffected: cost is computed from the requested resolution tier, independent of the actual pixel dimensions.

⚠️ The 1080p tier produces an actual height of 1088, not 1080 (H.264 macroblock alignment). This is encoder behaviour and affects neither tier selection nor billing.

Supplying input material#

Unlike the other video endpoints on this site, each kind of material is its own top-level field rather than an entry in a shared array:

{
  "model": "x-ai/grok-imagine-video-1.5",
  "prompt": "Make the water crash down and slowly pan out the camera",
  "image": { "url": "https://…/waterfall.png" },
  "reference_images": [{ "url": "https://…/style.png" }]
}

⚠️ The address must be wrapped in an object ({"url": "…"}); a bare string is not accepted and returns a 400 explaining the correct form.

⚠️ reference_audios is not supported yet. That upstream field accepts preset voice identifiers (voice_id), not an audio file — the two are semantically different. Supplying it returns a 400 rather than being silently ignored.

Billing#

cost = actual output seconds × resolution tier rate
     + input image count × per-image rate

Output seconds are taken from the value the upstream returns, not from the requested duration — for image-to-video the output length follows the material.

Resolution is the only tier dimension for the output charge; aspect_ratio takes effect but does not change the rate. First frame, last frame and reference images all count toward the input image total.

Cost is reserved at submit time from the requested duration and resolution, then settled against actual usage with the difference released.

Task id#

The returned request_id is the Amux task id, not the upstream task handle. All retrieval paths accept only this id: GET /v1/tasks/{id} and the xAI-shaped alias read the same task.