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.
# The SDK automatically creates an idempotency key and reuses it for automatic retries.
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 SDKs create an Idempotency-Key and reuse it for automatic retries. For manual retries, reuse the original key. Router can hold the connection for up to 10 minutes.

When a request fails, Router sends an X-Comfy-Error-Type response header explaining why. A 422 means Router rejected the input before calling the provider. Download generated assets promptly because result URLs can expire.

Headers

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

Using the Router API

Model discovery, validation errors, retries, and billing.

Limitations

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