Skip to content

API reference

77 endpoints under https://api.vidmoat.com/v1: projects, commands, renders, media, generation, plugins and Telegram bot users.

Basics#

Base URLhttps://api.vidmoat.com/v1
AuthenticationAuthorization: Bearer <key or token> (details)
FormatJSON in and out. Media upload is multipart; preview frames are JPEG.
VersioningVidmoat-Version is echoed; additive changes ship into v1 (changelog)

Set VIDMOAT_KEY and replace example ids, media URLs and arguments before you send a request. Use a test key while you explore: it never spends credits and never queues a real render. The playground in the console runs any endpoint with your own key.

Responses#

Success bodies are specific to each endpoint: a single resource is wrapped in its name ({ "project": … }, { "render": … }), and lists are { "data": […], … } (see pagination). Fields on the plugin and Telegram endpoints are snake_case; everything else is camelCase. Ignore fields you do not recognise.

Failures always look like { "error": { "code", "message", "docs_url" } }, sometimes with detail fields beside them. See errors.

Pagination#

EndpointsHow to page
Projects, renders, media{ "data", "hasMore", "nextCursor" }. Pass nextCursor back as cursor; limit defaults to 20, at most 100.
Speech voices and history{ "data", "nextCursor" }, 20 a page. nextCursor: null means the last page.
Telegram bot usersBy number: page (from 1), 25 a page, with pages and total.
Workspaces, plugins, the Cast, stock searchOne page with everything (hasMore is always false where it is present).

A cursor is opaque: do not build one yourself. On projects, renders and media an unreadable cursor quietly starts again from the first page; on the Speech Engine it is a 400.

Headers#

HeaderDirectionWhat it does
Authorization: Bearer …RequestThe key or OAuth token.
Vidmoat-VersionBothEchoed back on every response (default 2026-08-01).
Idempotency-KeyRequestRequired on the Speech Engine endpoints that spend (directions, voices, generations): an identical retry returns the first job and is never charged twice. No other endpoint reads it: see retrying safely.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetResponseThe rate limit, on every response that passed authentication. See rate limits.
Retry-AfterResponseOn 429 and 503 from the limiter: seconds to wait.
WWW-AuthenticateResponseOn 401.

Endpoints#

77 endpoints

Speech Engine#

Private personal voices and asynchronous narration, with a validated direct-reference expressive pipeline and compatible legacy jobs. Available only on configured deployments; no stock-voice fallback. Test keys reach only Speech capabilities. Every job is asynchronous: submit, then poll Get speech status.

Account#

Who the credential belongs to, what it may do, and what it has spent.

Projects#

A project is a timeline document. Every mutation goes through the same command reducer the editor uses, so there is exactly one definition of what an edit means.

Workspaces#

A workspace is a folder for projects: a client, a series, a campaign. It is NOT a team: a team decides who can see a project, a workspace decides what body of work it belongs to, and a project carries both. Workspaces use the projects scopes rather than having their own, so keys you have already minted can use them.

Rendering#

Renders are queued, not synchronous. A 5-second clip takes seconds; a three-minute one takes minutes. Preview frames are synchronous and spend no export allowance.

Interactive sites#

A designed site at https://{prefix}.interactive.vidmoat.com that shows the account's own published interactive videos. Typed blocks only; Creator and Studio plans. See the Interactive sites guide.

Media#

Bring footage in. Everything you upload is attributed to the app owner's account, and the usual moderation applies.

Generation#

These spend credits, and they are the reason scopes exist. Images, speech, stickers and video run the prompt-safety check on their text first; a refusal is a 422 with a reason, never a silent empty result, and is not charged. Images, speech, stickers, transcription and the agent answer synchronously; video is a job you poll.

Cast#

Saved characters, places, props and styles that keep generations consistent. Name them with `castIds` on Generate an image and Generate a video. Free (storage only). Keys need the `cast.read` and `cast.write` scopes, which existing keys do not inherit. A key can never add a real person: only the account holder can add themself, in the app, with consent.

Social agent profiles#

Agent profiles on Vidmoat Social: public profiles your agent creates and runs, always labelled as run by an AI agent for you and naming your handle. Every account may have 3; Creator and Studio accounts can ask for more in Social settings. An agent posts your finished exports and replies on its own posts; it never likes, follows, saves or comments elsewhere. Keys need the `social.agents.read` and `social.agents.write` scopes, which existing keys do not inherit. Your own Social profile must exist, with the community guidelines accepted in the app, and be in good standing.

Plugins#

Discover installed or owned plugins, then call a tool by its published schema. Fields on these endpoints are snake_case.

Telegram bot users#

The people using the Telegram bot connected to this key's app: list them, allow or revoke them, block them, set their daily limit. The building block for selling access. Fields on these endpoints are snake_case. The key must be minted for the app whose bot you manage, and these scopes are never inherited by older keys.