API Reference

Files

Fields like the image of a fake text message or a character avatar take a file key rather than a url, because the renderer reads them straight out of your workspace storage. This endpoint puts a file there and hands back that key.

POST/v1/files

Upload a file

Send the bytes as multipart form data, or a url for Vsub to fetch. The file is converted the same way the pickers in the app convert one, so images come back as png and videos keep a thumbnail.

Body

file

file

The file itself, sent as multipart form data under the field name file. Images, gifs, and .mp4 or .mov videos.

url

string

Where to fetch the file from instead, sent as json. The url has to be reachable without authentication. Pass either this or file.

Response fields

filerequired

string

The key to pass to a video endpoint, such as the image of a message or the avatar of a character on Fake Text.

urlrequired

string

Where the file now lives, handy for checking the upload landed. Video endpoints want the key, not this.

previewFilerequired

string

Key of a smaller copy the app shows while editing. Nothing in the API asks for it.

thumbnailFile

string

Key of a still frame. Videos only.

fileTyperequired

"image" | "gif" | "video"

What Vsub decided the file is, from its mime type.

widthrequired

number

Pixel width. Pass it along as imageWidth on a fake text message so the attachment is laid out at the right size.

heightrequired

number

Pixel height.

duration

number

How long a gif or video runs, in milliseconds. Left out for still images.

Request

curl -X POST "https://api.vsub.io/v1/files" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -F "file=@screenshot.png"

# or point it at a url instead
curl -X POST "https://api.vsub.io/v1/files" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.example.com/screenshot.png" }'

Response 200

{
  "file": "expire-30-user-image-9f1c2a44-1f6e-4a2a-9a01-2b8d6f0c4e11.png",
  "previewFile": "user-preivew-image-4b91d0c2-88a3-4f2e-9a77-0c1e5d2a7b93.png",
  "url": "https://files.vsub.io/expire-30-user-image-9f1c2a44-1f6e-4a2a-9a01-2b8d6f0c4e11.png",
  "fileType": "image",
  "width": 1080,
  "height": 1253
}

Uploads follow the storage rules of your plan, so on plans where files expire the key stops resolving after the same number of days as files uploaded in the app. Upload shortly before creating the video that uses it.

curl -X POST "https://api.vsub.io/v1/files" \ -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \ -F "file=@screenshot.png" # or point it at a url instead curl -X POST "https://api.vsub.io/v1/files" \ -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.example.com/screenshot.png" }'

{ "file": "expire-30-user-image-9f1c2a44-1f6e-4a2a-9a01-2b8d6f0c4e11.png", "previewFile": "user-preivew-image-4b91d0c2-88a3-4f2e-9a77-0c1e5d2a7b93.png", "url": "https://files.vsub.io/expire-30-user-image-9f1c2a44-1f6e-4a2a-9a01-2b8d6f0c4e11.png", "fileType": "image", "width": 1080, "height": 1253 }