Use Grok Imagine Video with Comfy Router

Call xai/grok-imagine-video through Comfy Router: endpoint, request shape and the response Router returns.

API Reference for xai/grok-imagine-video, served by Comfy Router from xAI.

Quick start

Create a key at platform.comfy.org/profile/api-keys and export it as COMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP.

Model ID: xai/grok-imagine-video

Endpoint: POST https://api.comfy.org/v2/models/xai/grok-imagine-video

Python

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Each call sends a fresh
# Idempotency-Key and waits up to 10 minutes for the finished result.
with Comfy() as client:
    result = client.models.run(
        "xai/grok-imagine-video",
        {
            "duration": 4,
            "prompt": "a single red maple leaf falling onto still water, slow motion",
        },
    )

print(result)

Schema

Input

aspect_ratio · string · default: "\"16:9\""

Aspect ratio of the generated video

Possible values: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3

duration · integer · default: "8"

Video duration in seconds. Range [1, 15]. Default 8.

Range: 1 to 15

image · object

Input image object for xAI endpoints

image.type · string

Type of the image input

Possible values: image_url

image.url · string · required

URL of the input image (public URL or base64-encoded data URI)

model · string

Model to be used

output · object

Optional output destination for generated video

prompt · string · required

Prompt for video generation. Maximum 4,096 characters.

reference_images · object[]

One or more reference images to guide the video generation (reference-to-video mode). Mutually exclusive with image. Router forwards application/json only and neither this object nor XAIImageObject accepts a file_id, so file-backed image inputs are not supported on this route.

reference_images[].url · string · required

URL of the reference image. Supports HTTPS URLs (public) or base64-encoded data URLs (e.g., data:image/jpeg;base64,…).

resolution · string

Resolution of the output video

size · string

Size of the output video

user · string

A unique identifier representing your end-user

Generated from the schema Router serves at GET /v2/models/xai/grok-imagine-video/openapi.json, the same document it validates a call against before the request reaches the provider.

Output

block_reason · string

If the request was blocked by input moderation, contains the block reason

model · string

The model used to generate the video

status · string

Status of the deferred request: “pending” or “done”

Possible values: pending, done

usage · object

Usage information for the video generation request

usage.cost_in_usd_ticks · integer

The cost of this request expressed in USD ticks. One USD cent equals 100,000,000 ticks, so one US dollar equals 10,000,000,000 ticks.

video · object

A generated video from xAI

video.duration · integer

Duration of the generated video in seconds

video.respect_moderation · boolean

Whether the video generated by the model respects moderation rules

video.url · string

Download URL for the generated video. Router re-hosts the video onto Comfy storage and rewrites this field, so it is normally a Comfy-signed URL valid for up to 24 hours - signed for 24 hours when minted and replayed from a 23-hour memo, so a later poll can hand back one with as little as an hour left. When the re-host could not be performed the field keeps xAI’s own short-lived URL instead. NULLABLE: a success whose url is empty is not a completed generation. Either way the link expires, so download the video rather than storing the URL.

Examples

Input

{
  "duration": 4,
  "prompt": "a single red maple leaf falling onto still water, slow motion"
}

Output

{
  "model": "grok-imagine-video",
  "status": "done",
  "usage": {
    "cost_in_usd_ticks": 3500000000
  },
  "video": {
    "duration": 4,
    "respect_moderation": true,
    "url": "https://example.invalid/xai/grok-imagine-video/generated.mp4"
  }
}

Before you ship

The snippets above are the shortest working call. Three things are the same for every model and are documented once on the Comfy Router headers page: send an Idempotency-Key on every paid call and reuse it when you retry, expect the connection to be held up to Router’s 10 minute deadline, and keep X-Comfy-Request-Id from every response. The SDKs do all three for you; the cURL tab does none of them. On failure, X-Comfy-Error-Type names the bucket, and a 422 means the body failed the model’s schema and was never billed.

Headers

Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.

Quick Start

Typed error handling in Python and TypeScript, reading the 422, walking the catalog.

Limitations

What Router does not do today, and what to use instead.