Private beta30 seats for the $9 test film.Check a niche

DocsTeams and API

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.

Status: Planned

Planned

This page describes a feature that is designed but not built yet. The changelog shows what is live today. Changelog

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 /films starts 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}/package returns 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 /channels lists 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”.