API Reference

Video status

One endpoint reports on every video you create, whichever template made it. Creation returns immediately, so poll here or set a webhookUrl and skip polling entirely.

GET/v1/videos/:id

Get a video

Returns the current state of a video created with your API key. Status transitions: processing -> rendering -> completed | failed. Poll every 15 to 30 seconds.

Path parameters

idrequired

string

The video id returned when you created the video.

Response fields

statusrequired

string

processing while scenes, voice over and images are generated, rendering while the mp4 is produced, completed when the video is ready, and failed if something went wrong.

step

string

Finer grained progress within processing, such as create-scenes, create-vocal or create image.

videoUrl

string

Direct download link for the mp4, present once the video is completed and was rendered. The link needs no authentication, so you can hand it straight to a client or downloader.

editorUrl

string

Opens the video in the Vsub editor, where you can change scenes, images and subtitles before exporting.

error

string

Why the video failed, present only when status is failed.

Request

curl "https://api.vsub.io/v1/videos/9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"

Response 200

{
  "id": "9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f",
  "status": "completed",
  "step": "completed",
  "render": true,
  "createdAt": "2026-08-04T09:20:11.000Z",
  "editorUrl": "https://vsub.io/workspace/editor/9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f",
  "videoUrl": "https://files.vsub.io/output-9f0c1d5e.mp4"
}

A video created without render reaches completed as soon as generation is done and has no videoUrl. Open editorUrl to review it, or export it with Render video.

Need to create a video first? Pick a template: AI video V2, Roblox rant, Fake Text, Quiz, Add Captions.