GET

/v1/schemas/grok/video/v1/videos/generations

Accept:

kind inputactivity videohash ae7ab7ac…extracted Oct 23, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `592b360ae23c430da1461f6cadcab06ccc85a577134893ff1f73c4c7879d116b` { "fetchedAt": 1792732296, "extractorVersion": "1", "verifiedAt": null }

Request body

12 properties · 0 required · 9 $defs

property	type	description	constraints
aspect_ratio	enum	Aspect ratio of the generated video. Ignored for image-to-video (first-frame `image` input): the aspect ratio is always derived from the input image.	1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 3:2 · +3 more · nullable
duration	any	Video duration in seconds. Range: [1, 15]. Default: 8. Also accepts `seconds` for OpenAI API compatibility. Accepts both number (8) and string ("8") values.	1 ≤ n ≤ 15 · format: int32 · default: 8
image	ImageUrl	Optional input image for image-to-video generation. If provided, generates video with this image as the first frame. Also accepts `input_reference` for compatibility (same semantics — first frame).	nullable
keyframes	VideoKeyframe[]	Optional mid-video keyframe anchors, strictly between the endpoint pins (`image` as the first frame, `last_frame` as the last). Each entry pins an image to appear literally at its timestamp. Only supported by select video models; at most 4 entries.	items ≤ 4
model	any	Model to be used.
output	VideoOutput	Optional output destination for generated video.	nullable
prompt	string	Prompt for video generation. Required for text-to-video (T2V) and reference-to-video (R2V). Optional for image-to-video (I2V) — when omitted, the model generates a video from the image alone.
reference_audios	AudioUrl[]	Optional reference audio clips (voice identity) for reference-to-video generation. Each entry supplies a clip via `url` or selects a voice via `voice_id`; caller-supplied clips must be at most 15 seconds long. Only supported by select video models; at most 3 e…	items ≤ 3
reference_images	ImageUrl[]	Optional reference images for reference-to-video (R2V) generation. When provided generates video using these images as style/content references.
resolution	enum	Resolution of the generated video.	480p \| 720p \| 1080p · nullable
storage_options	StorageOptions	Optional output storage configuration. When present, the generated video is stored in the Files API and a `file_output` reference is returned in the response alongside the ephemeral URL.	nullable
user	any	A unique identifier representing your end-user.

Types

9 $defs

AudioUrlobject

Reference audio input for video generation. Accepts a caller-supplied clip via `url` or selects a voice via `voice_id`. Exactly one source must be set.

url	any	Base64-encoded audio data URL (e.g. `data:audio/wav;base64,...`) or an http(s) URL to a downloadable audio clip of at most 15 seconds. Mutually exclusive with `voice_id`.
voice_id	any	Identifier of a first-party preset voice (e.g. "ara"; same voice identifiers as the TTS API), resolved server-side to a curated reference clip from the model's voice-preset catalog. Models configured for custom voices also accept a custom voice identifier. Mut…

ImageUrlobject

Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.

file_id	any	File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded.
url	string	Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set.

PublicUrlInputboolean | object

Accepts either `true` (create public URL with defaults) or a configuration object with explicit options.

PublicUrlOptionsobject

Configuration for creating a public URL alongside file storage.

expires_after

any

Seconds from now until the public URL expires. Must be between 3600 (1 hour) and 2592000 (30 days).

format: int64

Configuration for storing generation output in the Files API. When provided in a generation request, the output is stored as a permanent file and a `file_output` reference is included in the response.

expires_after	any	Seconds from now until the file auto-expires. Maximum 2592000 (30 days). If omitted, the file does not expire.	format: int64
filename*	string	Filename for the stored file.
public_url	boolean \| object	`true` = create public URL with default options (no independent expiry). Object = create public URL with explicit configuration. Omit = no public URL (file stored privately).	nullable

VideoAspectRatioenum

Aspect ratio for video generation.

1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 · +3 more

VideoKeyframeobject

A mid-video keyframe anchor: the image appears literally at `timestamp_s` seconds, strictly inside the clip (endpoints use `image` / `last_frame`). Timestamps snap to the engine's keyframe grid (one anchor per 1/3 second).

image*	ImageUrl	The pinned image.
timestamp_s*	number	Anchor time in seconds, strictly inside the clip (0 < t < duration).	format: float

VideoOutputobject

Output destination for generated video.

upload_url*

string

Signed URL to upload the generated video via HTTP PUT, e.g. an S3 / GCS presigned URL or an Azure Blob SAS URL. The PUT sends `Content-Type: video/mp4`, plus `x-ms-blob-type: BlockBlob` for Azure Blob Storage hosts.

VideoResolutionenum

Resolution for video generation.

480p | 720p | 1080p

Validate a payload

before you spend tokens

shell

$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"grok","endpointId":"v1/videos/generations","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}