---
title: "Get the result of a deferred video generation request."
method: GET
path: "/v1/videos/{request_id}"
tags: ["v1"]
---

# Get the result of a deferred video generation request.

`GET /v1/videos/{request_id}`

Returns the current status of a video generation job. When the job completes
successfully the response contains the generated video URL. When the job fails
the response contains a structured `error` object with a machine-readable
`code` and a human-readable `message`.

Both successful and failed completions return HTTP 200 — use the `status`
field (`"done"` or `"failed"`) to distinguish between the two.

## Path parameters

- `request_id` string, required

## Response `200`

Video generation completed or failed. Check the `status` field to determine the outcome.

- VideoResponse — Video generation response.
  - `error` VideoError — Structured error returned when video generation fails.
    - `code` 'invalid_argument' | 'permission_denied' | 'failed_precondition' | 'service_unavailable' | 'internal_error', required — Machine-readable error codes for video generation failures. These are the codes that can appear in `VideoError.code` when polling a deferred video generation result. Authentication, model-not-found, and synchronous rate-limit errors are returned as HTTP errors and never appear in `VideoError`. Engine overload encountered mid-generation surfaces here as `service_unavailable` (HTTP 503). Serializes to/from snake_case strings (e.g. `"invalid_argument"`, `"internal_error"`) for JSON compatibility.
    - `message` string, required — Human-readable error message describing the failure.
  - `model` string, nullable — The model used to generate the video. Omitted when status is "failed".
  - `progress` integer, nullable — Approximate completion percentage for the video generation task (0-100). - When status is "pending": progress is between 0-99, indicating current completion. - When status is "done": progress is 100. - When status is "failed": progress is omitted.
  - `status` string, required — Status of the video generation: "done" when the video is ready.
  - `usage` MediaUsage — Billing and cost information for media generation requests (image and video). The optional token fields follow the OpenAI Images API shape (`input_tokens` / `output_tokens` / `total_tokens` with per-side detail objects) and are populated only for image models with token-based usage reporting. They are omitted entirely for models billed per image and for video requests.
    - `cost_in_usd_ticks` integer, required — 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.
    - `input_tokens` integer, nullable — Total input tokens: prompt text tokens + input image tokens (the sum of `input_tokens_details`, where `cached_tokens` is a subset of `text_tokens`, not additive).
    - `input_tokens_details` MediaInputTokensDetails — Breakdown of media generation input tokens.
      - `cached_tokens` integer, required — Text tokens served from cache from previous requests (a subset of `text_tokens`).
      - `image_tokens` integer, required — Input image tokens, as reported by the image engine.
      - `text_tokens` integer, required — Prompt text tokens consumed by the prompt-rewriting (upsampler) LLM, including any served from cache.
    - `output_tokens` integer, nullable — Total output tokens: rewritten-prompt text tokens + reasoning tokens + generated image tokens (the sum of `output_tokens_details`).
    - `output_tokens_details` MediaOutputTokensDetails — Breakdown of media generation output tokens.
      - `image_tokens` integer, required — Generated image tokens, as reported by the image engine.
      - `reasoning_tokens` integer, required — Reasoning (thinking) tokens generated by the prompt-rewriting (upsampler) LLM.
      - `text_tokens` integer, required — Rewritten-prompt text tokens generated by the prompt-rewriting (upsampler) LLM, excluding reasoning tokens.
    - `total_tokens` integer, nullable — Total tokens (input + output).
  - `video` GeneratedVideo — Generated video.
    - `duration` integer, required — Duration of the generated video in seconds.
    - `file_output` FileOutput — Information about a generated file stored in the Files API.
      - `expires_at` integer, nullable — Unix timestamp (seconds) when the stored file expires and will be automatically deleted. Only present when the file has an expiration.
      - `file_id` string, required — Files API file_id of the stored file.
      - `filename` string, required — Filename of the stored file.
      - `public_url` string, nullable — Public URL for the stored file. Only present when the request included `storage_options.public_url` and creation succeeded.
      - `public_url_error` string, nullable — Human-readable error when `storage_options.public_url` was set but public URL creation failed. The file was stored successfully.
      - `public_url_expires_at` integer, nullable — Unix timestamp (seconds) when the public URL expires. Present when the public URL has an expiry, either from an explicit `expires_after` in the request or inherited from the file's TTL.
    - `respect_moderation` boolean, required — Whether the video generated by the model respects moderation rules. The field will be true if the video respects moderation rules. Otherwise the field will be false and the video url field will be empty.
    - `storage_error` string, nullable — Human-readable error when `storage_options` was set but the upload failed. Absent on success or when storage was not requested.
    - `url` string, nullable — A url to the generated video.

## Other responses

- `202` — Video generation still in progress
- `400` — Bad request. The request is invalid or an invalid API key is provided.
- `404` — Not found. No deferred video could be found with the given request_id.

---

[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)