# Vidmoat

> The engine behind the Vidmoat video editor, exposed as a REST API: create a project,
> apply edit commands, render it, read the result. Editing runs through the same command
> reducer the editor itself uses, so anything doable by hand is doable over HTTP.
> There is also an AI editing agent, transcription, generation (image/video/speech),
> stock search, previews, an MCP server, signed webhooks and Telegram bots.

## Facts worth having before you read anything else

- Base URL: `https://api.vidmoat.com/v1`
- Auth: `Authorization: Bearer vmk_live_…` or `vmk_test_…` (API key), or an OAuth 2.0
  bearer token from Sign in with Vidmoat when acting on an end user's own account.
- Test keys are free on every plan, never spend credits and never queue a real render,
  but projects and timeline edits they make are real. Renders and generation return samples.
- Scopes are enforced. A missing scope returns 403 `insufficient_scope` naming the scope.
- A scope is necessary but never sufficient: the account's plan and credit balance
  still apply, so `ai.video` on a plan without it returns 402 `plan_required`.
- Errors are `{ "error": { "code", "message", "docs_url" } }`. Branch on `code`.
- Commands in a batch succeed or fail one by one; read `results[]`, not just the status.
- There is no Idempotency-Key. Do not resend a POST after a timeout without re-reading state.
- Webhooks are configured in the signed-in console; there is no /v1/webhooks route.
- GET /v1/schema/commands requires a bearer token, but no additional scope.
- Every page below has a Markdown twin: add `.md` to its URL.

## Full text

- [Everything, as one markdown document](https://developer.vidmoat.com/llms-full.txt): every page below,
  including every endpoint with its parameters and examples, in a single fetch.

## Guides

- [Vidmoat developer documentation](https://developer.vidmoat.com/developer/docs.md): The engine behind the Vidmoat editor, as 35 REST endpoints, an MCP server, signed webhooks and Telegram bots. Create a project, apply edit commands, render it, read the result.
- [Quickstart](https://developer.vidmoat.com/developer/docs/quickstart.md): From no account to a rendered video in about five minutes, with a free test key that never spends credits.
- [Authentication](https://developer.vidmoat.com/developer/docs/authentication.md): One header, two kinds of token. Which one you want depends on whose account the work belongs to.
- [Scopes](https://developer.vidmoat.com/developer/docs/scopes.md): 18 permissions, resource-dot-action. Coarse on purpose: you should be able to pick the right ones without reading a manual.
- [Projects and commands](https://developer.vidmoat.com/developer/docs/concepts/projects-and-commands.md): A project is one timeline document, and the only way to change it is a list of commands run through the same reducer the editor uses.
- [Renders and previews](https://developer.vidmoat.com/developer/docs/concepts/renders-and-previews.md): A render is a queued job that produces the final file and uses your export allowance. A preview is an instant frame or composition that costs nothing.
- [Credits and plans](https://developer.vidmoat.com/developer/docs/concepts/credits-and-plans.md): What costs credits, what uses your monthly allowance, what is free, and how a plan decides what a scope can reach.
- [Test and live keys](https://developer.vidmoat.com/developer/docs/concepts/test-and-live-keys.md): Test keys let you build the whole integration for free. Here is exactly what they fake and what they do for real.
- [Webhooks](https://developer.vidmoat.com/developer/docs/webhooks.md): Signed HTTP notifications when a render finishes, credits run low or something happens on your Telegram bot. How to receive them, verify them and stay correct when one goes missing.
- [Video preview](https://developer.vidmoat.com/developer/docs/preview.md): Play the app compositor while editing, and inspect exact frames before exporting. None of it uses your export allowance.
- [Editor starter](https://developer.vidmoat.com/developer/docs/editor-starter.md): A working, downloadable React video editor you can run locally and adapt: your frontend, our video engine.
- [Errors and retries](https://developer.vidmoat.com/developer/docs/errors.md): Stable machine codes, what each one means, and which requests are safe to send again.
- [Rate limits](https://developer.vidmoat.com/developer/docs/rate-limits.md): How many requests a key may make, what the headers mean, and how to back off without losing work.
- [Build your own video platform](https://developer.vidmoat.com/developer/docs/build.md): The long-form guide to shipping an agentic or editor-style video product on the API: the document format, the command reducer, previews, renders, costs and both auth models.

## API reference

- [API reference](https://developer.vidmoat.com/developer/docs/api.md): 35 endpoints under https://api.vidmoat.com/v1: projects, commands, renders, media, generation, plugins and Telegram bot users.
- [Get the current account](https://developer.vidmoat.com/developer/docs/api/account/get-me.md): The owner of this credential: plan, credit balance, export allowance and limits, plus the scopes this key actually carries. The first call to make when a request is failing with 403 and you are not sure why.
- [Get usage](https://developer.vidmoat.com/developer/docs/api/account/get-usage.md): Request counts (with the error split) and credits spent, for the whole account and for this key's app, for building your own dashboard or a spend alarm.
- [Get the command schema](https://developer.vidmoat.com/developer/docs/api/account/get-command-schema.md): The full command vocabulary the editor accepts, verbatim from COMMAND_SCHEMA. A valid bearer token is required, but no additional scope is needed.
- [List projects](https://developer.vidmoat.com/developer/docs/api/projects/list-projects.md): List your projects, most recently updated first. Add ?workspace=<id> to list one folder, or ?workspace=unfiled for the ones in none.
- [Create a project](https://developer.vidmoat.com/developer/docs/api/projects/create-project.md): Create an empty 16:9, 1920x1080, 30 fps project, optionally applying a first batch of commands. Counts against the plan's project limit.
- [Get a project](https://developer.vidmoat.com/developer/docs/api/projects/get-project.md): One project. The default clips view lists tracks and clips; ?view=document returns the full edit document.
- [Update a project](https://developer.vidmoat.com/developer/docs/api/projects/update-project.md): Rename, or change output settings: aspect ratio, frame rate, background, width and height. Timeline edits go through commands.
- [Delete a project](https://developer.vidmoat.com/developer/docs/api/projects/delete-project.md): Delete a project and its render jobs. This cannot be undone.
- [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands.md): Apply an ordered list of edit commands. This is the only way to change a timeline, and it is the same reducer the editor calls: anything you can do by hand you can do here.
- [Validate commands](https://developer.vidmoat.com/developer/docs/api/projects/validate-commands.md): Dry-run a command batch against the current document and get back per-command results and layout lint, without saving anything. Needs only a read scope.
- [List workspaces](https://developer.vidmoat.com/developer/docs/api/workspaces/list-workspaces.md): Every workspace you can see, personal and team, with how many projects are in each. Always one page (at most 60 per scope).
- [Create a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/create-workspace.md): Create a workspace. Pass teamId to make it a shared one.
- [Update a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/update-workspace.md): Rename, recolour, change the icon or reorder a workspace.
- [Delete a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/delete-workspace.md): Delete a workspace. The projects inside are KEPT and become unfiled; the response returns how many.
- [File a project](https://developer.vidmoat.com/developer/docs/api/workspaces/set-project-workspace.md): File a project into a workspace, or send workspaceId: null to take it out.
- [Queue a render](https://developer.vidmoat.com/developer/docs/api/renders/create-render.md): Queue an export of a project's saved document. Resolution cap, watermark and concurrency come from the owner's plan.
- [List renders](https://developer.vidmoat.com/developer/docs/api/renders/list-renders.md): List your render jobs, newest first. Filter by projectId or status, and page with cursor.
- [Get a render](https://developer.vidmoat.com/developer/docs/api/renders/get-render.md): Poll a job: PENDING, then PROCESSING, then COMPLETED or FAILED, with progress 0 to 100 and the download URL on completion.
- [Preview a project](https://developer.vidmoat.com/developer/docs/api/renders/get-preview.md): Metadata and layout lint (default), approximate composition HTML, or an exact rendered frame. For live playback with the app compositor, use the embedded player described in the video-preview guide.
- [List media](https://developer.vidmoat.com/developer/docs/api/media/list-media.md): List the files uploaded or imported on the account, newest first, with the URLs a clip src can point at. Generated media is not included.
- [Upload a file](https://developer.vidmoat.com/developer/docs/api/media/upload-media.md): Upload a file directly, as multipart form data, up to 32 MB per request and within your plan's upload and storage limits. For larger files, import from a URL.
- [Import from a URL](https://developer.vidmoat.com/developer/docs/api/media/import-media.md): Fetch a public http(s) URL server-side, up to your plan's upload cap or 512 MB, whichever is smaller. Destinations pass through the SSRF guard, so private ranges and metadata endpoints are refused.
- [Search stock media](https://developer.vidmoat.com/developer/docs/api/media/search-stock.md): Search the stock library by keyword, then import a result's downloadUrl with /v1/media/import.
- [Transcribe media](https://developer.vidmoat.com/developer/docs/api/generation/create-transcription.md): Word-level timings for captions. Feed words[] straight into an addCaptions command.
- [Generate speech](https://developer.vidmoat.com/developer/docs/api/generation/create-speech.md): AI-generated speech, up to 1,000 characters (longer text is cut and the response says where). provider:auto/grok/openai; optional voiceId, language, speed, and OpenAI instructions for delivery. quoteOnly:true quotes without spending. Auto may fall back after a confirmed quota rejection within maxCredits; a named voice stays pinned. Creator and Studio.
- [Generate an image](https://developer.vidmoat.com/developer/docs/api/generation/create-image.md): Generate a still with optional referenceUrls (up to 5 images: your uploads or public HTTPS images). provider accepts grok, openai, vertex or auto (default). quoteOnly:true returns the initial and maximum credits without spending. Retain provider:auto with the quoted maxCredits to allow safe quota fallback; explicit providers never switch. OpenAI GPT Image 2.5 Flare costs 128 at 1k or 256 at 2k plus 8 per reference; Vertex costs 128/192 plus 2 per reference. Only the successful asset is charged. Studio.
- [Generate a sticker](https://developer.vidmoat.com/developer/docs/api/generation/create-sticker.md): Generate a cut-out sticker with a transparent background (a PNG, or an SVG when the vector fallback is used). Creator and Studio.
- [Generate a video](https://developer.vidmoat.com/developer/docs/api/generation/create-video.md): Start a generated clip with Grok, Alibaba HappyHorse or Wan 3.0. Returns a job to poll. Paid Studio only; trials and full-waiver promotions are excluded.
- [Get a generation job](https://developer.vidmoat.com/developer/docs/api/generation/get-generation-job.md): Poll a video generation job until it is COMPLETED or FAILED. Images, speech and stickers answer synchronously and have no job. A job that fails is refunded.
- [Run the editing agent](https://developer.vidmoat.com/developer/docs/api/generation/run-agent.md): Describe an edit in message and let the agent emit and apply the commands. One turn per call, charged once: you drive the loop. Works on every plan.
- [List plugins](https://developer.vidmoat.com/developer/docs/api/plugins/list-plugins.md): List installed and owned plugins and their available tools.
- [Call a plugin tool](https://developer.vidmoat.com/developer/docs/api/plugins/invoke-plugin-tool.md): Invoke an available plugin tool with its arguments. Test keys return a fixture without contacting the plugin.
- [List bot users](https://developer.vidmoat.com/developer/docs/api/telegram-users/list-telegram-users.md): The people who used the bot, 25 a page. Search with q (name, @username or id), sort=last_seen or spend.
- [Get a bot user](https://developer.vidmoat.com/developer/docs/api/telegram-users/get-telegram-user.md): One person, by numeric Telegram id or @username, with their standing, daily limit and usage. Works for somebody allowed before they ever messaged the bot.
- [Update a bot user](https://developer.vidmoat.com/developer/docs/api/telegram-users/update-telegram-user.md): Change one person: allowed (allowlist), blocked, daily_credits (null for the bot's default).

## Telegram bots

- [Telegram bots](https://developer.vidmoat.com/developer/docs/telegram.md): Connect a Telegram bot you made with BotFather. People who message it edit video in the chat with no Vidmoat account. You decide who may use it, what it can do and what it may spend; every credit comes out of your balance.
- [Access, features and limits](https://developer.vidmoat.com/developer/docs/telegram/access.md): Who can use your bot, what it can do for them, and the daily caps that keep its spending where you want it.
- [Your bot's words](https://developer.vidmoat.com/developer/docs/telegram/behaviour.md): Bot instructions, welcome and help text, a support contact, and your own plugins: how your bot talks and what it can call.
- [Managing people](https://developer.vidmoat.com/developer/docs/telegram/users.md): Block people, give them their own daily limit, add them to the allowlist or delete their data, in the console or from your server with /v1/telegram/users.
- [Sell access to your bot](https://developer.vidmoat.com/developer/docs/telegram/selling-access.md): Three patterns that work today with your own checkout. We do not take payments for you, and your users never pay Vidmoat.
- [Supporting your users](https://developer.vidmoat.com/developer/docs/telegram/support.md): What to set up so people can reach you, and where to look when somebody says the bot is not working.
- [Webhooks and your users' data](https://developer.vidmoat.com/developer/docs/telegram/webhooks-and-data.md): The events your bot sends to your systems, and what happens to the projects and history of the people who use it.

## MCP

- [MCP server](https://developer.vidmoat.com/developer/docs/mcp.md): Give your agent an editing timeline. MCP connects Claude, ChatGPT, Cursor or your own agent to Vidmoat's editing and media tools.
- [Plugins](https://developer.vidmoat.com/developer/docs/plugins.md): Extend what every Vidmoat agent can do. You host an MCP server; we proxy to it, namespace its tools, and expose them over both MCP and REST.

## Changelog

- [Changelog](https://developer.vidmoat.com/developer/docs/changelog.md): Developer-facing changes to the API, MCP server, webhooks, plugins and Telegram bots, newest first.

## Notes

- The console at https://developer.vidmoat.com/developer/apps is where a human mints
  keys. It is session-authenticated; an API key cannot mint another key.
- Any plan can connect over MCP by signing in from the assistant. Personal API keys and
  live developer keys are on the Studio plan ($49/month);
  Creator ($19/month) does not include it. Test keys work on any plan.

## What Vidmoat is, outside this API

- This host documents the developer platform only. The product is a hosted AI video
  editor at https://www.vidmoat.com, used in the browser or from Telegram via
  @vidmoat_bot (https://t.me/vidmoat_bot). The API and MCP are two more ways in, not
  the product.
- The canonical description, pricing and common misdescriptions live at
  https://www.vidmoat.com/llms.txt. Where these two files disagree, that one is right.
- The Vidmoat engine is hosted. The downloadable editor starter is a small custom
  frontend that connects to that hosted API, not a self-hosted copy of Vidmoat.