API reference
36 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": […], "hasMore": true, "nextCursor": "…" }. Pass nextCursor back as cursor for the next page (limit defaults to 20, at most 100). Telegram bot users page by number instead (page, 25 a page). 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" } }. See errors.
Endpoints#
36 endpoints
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 - POSTApply commands
/v1/projects/{id}/commandsprojects.write - POSTValidate commands
/v1/projects/{id}/validateprojects.read
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.
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 the editing agent
/v1/ai/agentai.agent
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.