Skip to main content
GET
Get the current durable state of a video
GET /v1/videos/{video_id} accepts a character+motion Render ID (render_), a MiniMax H3 generation ID (vid_), a character-animation generation ID (anim_), or a 2x video upscale ID (vsr_), and returns its current durable state. Poll every 3–5 seconds until the status is terminal, or use Watch Render for a push-based alternative on a Render-sourced ID. This endpoint replaces the retired GET /v1/renders/{render_id}.
GET /v1/renders/{render_id} no longer accepts GET — it now answers 405 Method Not Allowed, not 404, because other methods remain registered on that path. A router only answers 404 when a path has no method registered at all; here it still has at least one, so the retired method 405s instead. If your integration checked for a 404 to detect that the old route was gone, accept 405 too, or switch straight to this endpoint.

Request parameters

Response parameters

Returns 200 OK with a Video object.
A generated seed is a random 63-bit integer (0 to 2^63 − 1), so it almost always exceeds Number.MAX_SAFE_INTEGER (2^53 − 1). JavaScript’s JSON.parse silently rounds it — 4271960385017522688 in the example below would come back as a different number, and resubmitting that value won’t reproduce the video. Read the response with a 64-bit-safe JSON parser (for example, json-bigint) if you need the exact value, or supply your own seed no larger than 2^53 − 1 when creating the video.
This response does not include links — unlike the Render object returned by Render Video (from Character and/or Motion), a video fetched here carries no self/events/download shortcut. Use the same video_id for further Get Video calls, and Download Render for a Render-sourced ID.

Completion timing

On a Render-sourced video, completed_at can lag status reaching ready by up to roughly 30 seconds before it backfills — it isn’t a permanent gap. Decide whether a video is finished by checking status == "ready" or whether video_url is populated, not by whether completed_at is non-null.

Render-sourced example

H3-sourced example

Character-animation-sourced example

No seed field — it’s H3-only. queue_position and estimated_wait_seconds are present on both, null once the video is terminal.

Failed example

Examples

Authorizations

Authorization
string
header
required

Server-side SDK clients use a project API key. Remote MCP clients use an OAuth access token. Never expose a project API key in browser code.

Headers

X-Request-Id
string

Optional caller-supplied correlation ID, up to 128 characters. The service returns the effective value in the response header for tracing and support.

Required string length: 1 - 128
X-Viggle-Source
string

Optional source-channel label, up to 128 characters, used to attribute traffic to an SDK, integration, product surface, or internal workflow.

Required string length: 1 - 128

Path Parameters

video_id
string
required

Public video ID owned by the caller — a Render (render_ prefix), H3 generation (vid_), character-animation generation (anim_), or super-resolution task (vsr_).

Minimum string length: 1

Response

Current video state.

Unified, read-only full-state resource for a finished character+motion Render (render_ prefix), a MiniMax H3 video generation (vid_ prefix), or a character-animation generation (anim_ prefix). It carries no links field — unlike the Render object returned by POST /v1/renders, there is no unified self/events/download shortcut here.

stage is populated only when this is a Render-sourced video and status is processing; it is null in every other case, including every H3 and character-animation video. alpha_url is populated only on a Render-sourced video created with background_mode=transparent once it is ready; it is always null otherwise. seed is H3-only — present (not present-but-null; simply absent from the response) only on an H3-origin video, never on a Render-sourced or character-animation one.

id
string
required

Public video ID — a Render (render_ prefix), an H3 generation (vid_ prefix), or a character-animation generation (anim_ prefix).

Minimum string length: 1
status
enum<string>
required

Overall lifecycle. ready, failed, and cancelled are terminal states.

Available options:
queued,
processing,
ready,
failed,
cancelled
stage
enum<string> | null
required

Coarse pipeline phase, Render-only. Null except while a Render-sourced video's status is processing; always null for an H3 video.

Available options:
queued,
preparing,
generating,
finalizing,
ready,
failed,
cancelled,
analyzing,
rendering,
finishing
progress
integer | null
required

Best-effort completion percentage from 0 through 100; null when the source pipeline reports no estimate.

Required range: 0 <= x <= 100
video_url
string<uri> | null
required

Short-lived URL of the completed video; null until ready or when no output was produced.

alpha_url
string<uri> | null
required

Render-only alpha/mask video URL for transparent-background output; null on every H3 video and on any Render not created with background_mode=transparent.

created_at
string<date-time> | null
required

Creation timestamp. Render-sourced videos report nanosecond precision; H3 videos report second precision.

completed_at
string<date-time> | null
required

Terminal-state timestamp; null while the video is active. On a Render-sourced video this can lag status reaching ready by up to roughly 30 seconds before it is backfilled — use status (or check video_url), not the presence of this field, to detect completion.

error
object | null
required

Structured failure details when status is failed; otherwise null.

seed
integer<int64>

H3-only — present only on an H3-origin video, absent (not null) on Render-, character-animation-, and super-resolution-sourced ones. The seed actually used for generation — a caller-supplied value echoed back, or the value generated when POST /v1/videos omitted one. Generated seeds are random 63-bit integers (0 to 2^63−1), so they usually exceed 2^53 − 1 — parse this field with a 64-bit-safe JSON decoder; JavaScript's JSON.parse silently rounds it.

queue_position
integer | null

Present on H3 (vid_) and character-animation (anim_) videos. Exact number of tasks ahead while the video is queued. Present as null once processing starts and at terminal states; absent entirely for Render- and super-resolution-origin videos.

Required range: x >= 0
estimated_wait_seconds
integer | null

Present on H3 (vid_) and character-animation (anim_) videos. Approximate remaining wait in seconds, based on fleet-wide average render time and current queue/dispatch state — while queued, the expected wait to finish; while processing, the remaining average render time. Present as null at terminal states, for queued work below the top priority tier (which new top-tier work can keep preempting), or when no bounded estimate is available; absent entirely for Render- and super-resolution-origin videos.

Required range: x >= 0