API reference
Start films, read their status and fetch the upload package from your own tools. The API is planned; this page describes its design, which may still change.
Planned
Status: planned
The REST API is not open yet. This page describes the planned design; endpoints and fields can still change before it opens. The changelog announces when it opens and any change to what is described here.
Authentication
Create a key on /app/developers. Send it with every request in the header “Authorization: Bearer <your key>”. Keys belong to the workspace and use its minutes. Keep them secret; revoke and replace a key from the same page if it leaks.
Base URL: https://api.vidswarm.app/v1
Endpoints
POST /filmsstarts a film. Body fields: channel_id, topic, format (a sentence) or reference_url, length_minutes, language. Returns the film id, its status and the minutes it will reserve.GET /films/{id}returns the status, the current step, progress, minutes reserved and used, and the time of the last update.GET /films/{id}/packagereturns links to the video file, thumbnails, title options, description, tags, chapters, subtitles, Shorts and the source log, once the film is ready. Links expire after a while; request the package again for fresh ones.GET /channelslists the workspace’s channels with id, name, language and saved formats.
How API films run
Films started through the API run on hands-off within the channel’s settings: they stop only before spending minutes, and the reservation shown in the POST response is that approval. Nothing is published to YouTube through the API.
Errors
- 401: the key is missing or revoked.
- 402: not enough minutes for the film length.
- 404: the film or channel does not exist in this workspace.
- 422: a field is missing or invalid; the response names it.
- 429: too many requests; wait and retry.
Webhooks
Instead of polling GET /films/{id}, register a webhook to be told when a film is ready; see “Webhooks”.