API Reference

Background videos

The gameplay videos the editor's background video picker shows, as a list. Videos uploaded to this workspace come first, newest first, then the free ones every workspace can use.

GET/v1/background-videos

List background videos

Returns the background videos that are ready to render with. Videos still processing, or that failed to process, are left out.

Response fields

backgroundVideos[].idrequired

string

Pass it as backgroundVideoId when creating a quiz, Roblox or fake text video. The editor copies the same id from the copy button on each video.

backgroundVideos[].name

string

Name of the video, set on marketplace gameplays.

backgroundVideos[].freerequired

boolean

True for the free videos shared with every workspace.

backgroundVideos[].previewUrl

string

Small preview clip of the video.

backgroundVideos[].thumbnailUrl

string

Still image of the video, when one was made.

backgroundVideos[].duration

number

Length in seconds. backgroundVideoStartFrom can go up to this minus 1.

backgroundVideos[].width

number

Width in pixels.

backgroundVideos[].height

number

Height in pixels.

backgroundVideos[].createdAtrequired

string

When the video was uploaded, ISO 8601.

Request

curl "https://api.vsub.io/v1/background-videos" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"

Response 200

{
  "backgroundVideos": [
    {
      "id": "3f6d0c2e-8a41-4b5f-9e27-1c7a9b2d4e60",
      "free": false,
      "previewUrl": "https://storage.vsub.io/stock-videos/preview-3f6d0c2e.mp4",
      "thumbnailUrl": "https://storage.vsub.io/stock-videos/preview-3f6d0c2e.webp",
      "duration": 182.5,
      "width": 1080,
      "height": 1920,
      "createdAt": "2026-09-14T08:12:44.000Z"
    },
    {
      "id": "d752e7dd-73f2-4a58-8893-63f7d0c7b744",
      "free": true,
      "previewUrl": "https://storage.vsub.io/stock-videos/preview-d752e7dd.mp4",
      "duration": 600,
      "width": 1080,
      "height": 1920,
      "createdAt": "2025-03-02T10:00:00.000Z"
    }
  ]
}

Leave backgroundVideoId out and the video plays behind the workspace's default background, the same one the app would pick. An id that is not in this list is rejected with a 400.

{ "backgroundVideos": [ { "id": "3f6d0c2e-8a41-4b5f-9e27-1c7a9b2d4e60", "free": false, "previewUrl": "https://storage.vsub.io/stock-videos/preview-3f6d0c2e.mp4", "thumbnailUrl": "https://storage.vsub.io/stock-videos/preview-3f6d0c2e.webp", "duration": 182.5, "width": 1080, "height": 1920, "createdAt": "2026-09-14T08:12:44.000Z" }, { "id": "d752e7dd-73f2-4a58-8893-63f7d0c7b744", "free": true, "previewUrl": "https://storage.vsub.io/stock-videos/preview-d752e7dd.mp4", "duration": 600, "width": 1080, "height": 1920, "createdAt": "2025-03-02T10:00:00.000Z" } ] }