Skip to main content
GET
Get the current durable state of a video
GET /v1/videos/{video_id} accepts either a character+motion Render ID (render_ prefix, from Render Video (from Character and/or Motion)) or a MiniMax H3 text-to-video generation ID (vid_ prefix, from Generate Video (from Text), First Frame, or First-Last Frames) 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. 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

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) or an H3 text-to-video generation (vid_ prefix).

Minimum string length: 1

Response

Current video state.

Unified, read-only full-state resource for a finished character+motion Render (render_ prefix) or a MiniMax H3 text-to-video generation (vid_ 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 video. alpha_url is populated only on a Render-sourced video created with background_mode=transparent once it is ready; it is always null on an H3 video.

id
string
required

Public video ID — a Render (render_ prefix) or an H3 generation (vid_ 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.