Get video status — VisionStory API

Get a single video task by video_id, including its status (queued, creating, created, or failed) and, once ready, the download URL. Poll this to track generation progress.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Query parameters

video_idstringrequired

Id of the video task to fetch, as returned by POST /api/v1/video (the video_id field) or GET /api/v1/videos.

Responses

200Successful Response

application/json

dataGetVideoResponse | nullrequirednullable

Response for getting a single video

aspect_ratiostring

Output aspect ratio of the rendered video.

Values: 9:1616:91:1

Default: 9:16

cost_creditinteger

Credits charged for this video; 0 when the task failed (the charge is auto-refunded).

Default: 0

created_atintegerrequired

Unix timestamp (seconds) when the video task was created.

model_idstringrequired

Identifier of the model that produced this video; see GET /api/v1/models.

resolutionstring

Output resolution of the rendered video.

Values: 480p720p1080p2k

Default: 480p

statusstringrequired

Current task status: queued (waiting), creating (rendering), created (ready), or failed.

video_idstringrequired

Unique identifier of the video task. Use it to poll status or delete the video.

video_urlstring | nullnullable

Download URL of the finished video; empty until status is created. Videos are retained for 7 days.

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-side timestamp when the response was produced, in ISO 8601 format (UTC).

defaultError response. All failures share one envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (useful for AI agents).

application/json

errorErrorDetailrequired

codeintegerrequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

detailsstring | nullnullable

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullnullable

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.