API reference
77 endpoints under https://api.vidmoat.com/v1: projects, commands, renders, media, generation, plugins and Telegram bot users.
Basics#
| Base URL | https://api.vidmoat.com/v1 |
| Authentication | Authorization: Bearer <key or token> (details) |
| Format | JSON in and out. Media upload is multipart; preview frames are JPEG. |
| Versioning | Vidmoat-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#
| Endpoints | How 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 users | By number: page (from 1), 25 a page, with pages and total. |
| Workspaces, plugins, the Cast, stock search | One 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#
| Header | Direction | What it does |
|---|---|---|
Authorization: Bearer … | Request | The key or OAuth token. |
Vidmoat-Version | Both | Echoed back on every response (default 2026-08-01). |
Idempotency-Key | Request | Required 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-Reset | Response | The rate limit, on every response that passed authentication. See rate limits. |
Retry-After | Response | On 429 and 503 from the limiter: seconds to wait. |
WWW-Authenticate | Response | On 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.
- GETSpeech capabilities
/v1/speech/capabilitiesspeech.read - GETDiscover voices
/v1/speech/voicesspeech.read - GETCreator voice usage
/v1/speech/voices/{id}/usagespeech.read - POSTDirect a narration draft
/v1/speech/directionsspeech.generate - POSTCreate a voice
/v1/speech/voicesspeech.voices.write - GETGet a personal voice
/v1/speech/voices/{id}speech.read - PATCHUpdate a voice
/v1/speech/voices/{id}speech.voices.write - DELDelete a voice
/v1/speech/voices/{id}speech.voices.write - GETList speech history
/v1/speech/generationsspeech.read - POSTGenerate personal speech
/v1/speech/generationsspeech.generate - GETGet speech status
/v1/speech/generations/{id}speech.read - GETGet an audio download
/v1/speech/generations/{id}/audiospeech.read - POSTCancel queued speech
/v1/speech/generations/{id}/cancelspeech.generate - DELDelete generated speech
/v1/speech/generations/{id}speech.generate - POSTAuthorise narration for a project
/v1/speech/generations/{id}/importspeech.read
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.
- GETList projects
/v1/projectsprojects.read - POSTCreate a project
/v1/projectsprojects.write - GETGet a project
/v1/projects/{id}projects.read - PATCHUpdate a project
/v1/projects/{id}projects.write - DELDelete a project
/v1/projects/{id}projects.write - POSTDuplicate a project
/v1/projects/{id}/duplicateprojects.write - POSTApply commands
/v1/projects/{id}/commandsprojects.write - POSTValidate commands
/v1/projects/{id}/validateprojects.read - GETExport captions
/v1/projects/{id}/captionsprojects.read - GETGet the storyboard
/v1/projects/{id}/storyboardprojects.read - POSTCreate a storyboard
/v1/projects/{id}/storyboardprojects.write - POSTBuild a storyboard
/v1/projects/{id}/storyboard/runsai.agent - GETGet a board run
/v1/storyboard-runs/{id}projects.read - DELStop a board run
/v1/storyboard-runs/{id}ai.agent
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.
- POSTQueue a render
/v1/rendersrender.write - GETList renders
/v1/rendersrender.read - GETGet a render
/v1/renders/{id}render.read - POSTShare a render
/v1/renders/{id}/sharerender.write - GETList exports for choices
/v1/projects/{id}/interactiverender.read - POSTPublish choices
/v1/projects/{id}/interactiverender.write - GETPreview a project
/v1/projects/{id}/previewrender.read
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.
- GETList sites
/v1/interactive-sitesprojects.read - POSTMake a site
/v1/interactive-sitesprojects.write - GETCheck a prefix
/v1/interactive-sites/availabilityprojects.read - GETGet a site
/v1/interactive-sites/{id}projects.read - PATCHEdit a site
/v1/interactive-sites/{id}projects.write - POSTPublish a site
/v1/interactive-sites/{id}/publishrender.write
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.
- POSTTranscribe media
/v1/ai/transcriptionsai.transcribe - POSTGenerate speech
/v1/ai/speechai.speech - POSTGenerate an image
/v1/ai/imagesai.image - POSTGenerate a sticker
/v1/ai/stickersai.image - POSTGenerate a video
/v1/ai/videosai.video - POSTBring a still to life
/v1/ai/live-imagesai.video - GETGet a generation job
/v1/ai/jobs/{id}ai.video - POSTRun Otto, the editing agent
/v1/ai/agentai.agent
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.