---
title: "Generate a video from a text prompt and optionally an image.
This is an asynchronous operation that returns a request_id for polling."
method: POST
path: "/v1/videos/generations"
tags: ["v1"]
---

# Generate a video from a text prompt and optionally an image.
This is an asynchronous operation that returns a request_id for polling.

`POST /v1/videos/generations`

## Request body

- GenerateVideoRequest — Request to generate video for `/v1/videos/generations` endpoint
  - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3' — Aspect ratio for video generation.
  - `duration` integer, nullable — Video duration in seconds. Range: [1, 15]. Default: 8. Also accepts `seconds` for OpenAI API compatibility. Accepts both number (8) and string ("8") values.
  - `image` ImageUrl — 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` string, nullable — 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.
  - `model` string, nullable — Model to be used.
  - `output` VideoOutput — Output destination for generated video.
    - `upload_url` string, required — Signed URL to upload the generated video via HTTP PUT.
  - `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 (voice identity) for reference-to-video generation. Each entry selects a first-party preset voice via `voice_id`. Only supported by select video models; at most 3 entries. May be provided without `reference_images` (audio-only reference-to-video) — at least one reference of either kind selects the reference-to-video mode.
    - `voice_id` string, required — 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.
  - `reference_images` ImageUrl[] — Optional reference images for reference-to-video (R2V) generation. When provided generates video using these images as style/content references.
    - `file_id` string, nullable — 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.
  - `resolution` '480p' | '720p' | '1080p' — Resolution for video generation.
  - `storage_options` StorageOptions — 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` integer, nullable — Seconds from now until the file auto-expires. Maximum 2592000 (30 days). If omitted, the file does not expire.
    - `filename` string, required — Filename for the stored file.
    - `public_url` union — Accepts either `true` (create public URL with defaults) or a configuration object with explicit options. **Variant order matters for `#[serde(untagged)]`:** `Flag` must come before `Options` so that JSON `true`/`false` match `Flag` rather than falling through to the object variant. **Serialization note:** Proto→REST readback always constructs `Options(...)`, never `Flag`, so responses always emit the object form. `Flag` only appears on the deserialization (request) path.
      - boolean — `true` = create public URL with default options (no independent expiry). `false` = no public URL (equivalent to omitting the field).
      - PublicUrlOptions — Configuration for creating a public URL alongside file storage.
        - `expires_after` integer, nullable — Seconds from now until the public URL expires. Must be between 3600 (1 hour) and 2592000 (30 days). If omitted and the file has a TTL (`expires_after` on the file), the public URL inherits the file's expiry. If omitted and the file has no TTL, the public URL remains valid indefinitely until the file is deleted or the URL is explicitly revoked via `POST /v1/files/{file_id}/public-url/revoke`.
  - `user` string, nullable — A unique identifier representing your end-user.

## Response `200`

Video generation started successfully

- StartDeferredResponse — Response for starting a deferred operation.
  - `request_id` string, required — A unique request ID to poll for the result.

## Other responses

- `400` — Bad request. The request is invalid or an invalid API key is provided.
- `422` — Unprocessable Entity. There are missing fields in the request body.

---

[API](https://skmtc.net/x/apis/xai-s-rest-api.md) · [All operations](https://skmtc.net/x/apis/xai-s-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/x/xai-s-rest-api/revisions/8f6014272113/schema)