# Vidmoat developer documentation Everything on developer.vidmoat.com/developer/docs, in reading order, generated from the same source as the pages. Every page also has its own Markdown twin: add `.md` to its URL. Base URL: `https://api.vidmoat.com/v1` --- # Vidmoat developer documentation > The engine behind the Vidmoat editor, as 77 REST endpoints, an MCP server, signed webhooks and Telegram bots. Create a project, apply edit commands, render it, read the result. Vidmoat is a hosted video editor. Everything a person can do on its timeline, your code can do too: the API runs every edit through the same command reducer the editor uses, so there is no second definition of what an edit means. A command that works today keeps working. The base URL is `https://api.vidmoat.com/v1`. Requests and responses are JSON, except media upload (multipart) and preview frames (JPEG). Every request carries `Authorization: Bearer `. - [Quickstart](https://developer.vidmoat.com/developer/docs/quickstart): A first render in five minutes, with a free test key. - [API reference](https://developer.vidmoat.com/developer/docs/api): Every endpoint, with parameters, examples in curl, Node and Python, and the response. - [MCP server](https://developer.vidmoat.com/developer/docs/mcp): Connect Claude, ChatGPT or Cursor and let an agent edit on a real timeline. - [Telegram bots](https://developer.vidmoat.com/developer/docs/telegram): Connect your own bot. Your users edit video in chat, billed to your app. > **Note: 中文文档 / 中文文件.** Quickstart, MCP setup for Cherry Studio, Trae, Qwen Code, Kimi and Cursor, and network notes for mainland China, in [简体中文](https://developer.vidmoat.com/developer/docs/zh-cn/quickstart) and [繁體中文](https://developer.vidmoat.com/developer/docs/zh-tw/quickstart). ## How it fits together 1. **Mint a key** in the [console](https://developer.vidmoat.com/developer/apps). Test keys are free on every plan. 2. **Create a project** with `POST /v1/projects`. A project is one timeline document. 3. **Edit it with commands** through `POST /v1/projects/{id}/commands`: add clips, text, captions, effects, keyframes. 4. **Look before you render.** `GET /v1/projects/{id}/preview` returns layout lint and exact frames, for free. 5. **Render** with `POST /v1/renders`, then wait for the `render.completed` webhook or poll the job. - [Projects and commands](https://developer.vidmoat.com/developer/docs/concepts/projects-and-commands): The document, the reducer, and why every edit is a command. - [Renders and previews](https://developer.vidmoat.com/developer/docs/concepts/renders-and-previews): Jobs, statuses, frames and when to use which. - [Credits and plans](https://developer.vidmoat.com/developer/docs/concepts/credits-and-plans): What costs credits, what uses quota, and what is free. - [Test and live keys](https://developer.vidmoat.com/developer/docs/concepts/test-and-live-keys): What a test key really does, and what it does not fake. - [Webhooks](https://developer.vidmoat.com/developer/docs/webhooks): Signed events, verification in Node and Python, retries. - [Errors and retries](https://developer.vidmoat.com/developer/docs/errors): Stable error codes and what is safe to retry. > **Note.** Test keys do not spend credits or queue real renders, but project creation and timeline edits are real and persist on your account. Use a dedicated test project. Live keys need a plan with live API access (Studio, Team or Enterprise) and an app approved in review. ## What is deliberately not in the API Only the documented `v1` routes are a supported public contract. Internal routes carry no versioning promise. These are the ones people ask about: - **Browser recorder.** Holds a CPU core for about three minutes on the machine that serves the API. Per-app allowlist only. - **Inpainting.** One global CPU worker capped at 1/user, a single API caller would starve everyone else. - **Flows.** An orchestration product built on these primitives, not a primitive itself. - **Vidmoat Social.** Posting to a public feed as a third party is a moderation liability with no revenue. No scope grants it, and none will. - **Channels, CDS, admin, billing.** Internal surfaces with no versioning promise. They will be refactored without notice. ## Versioning Additive changes ship into `v1`: new fields, new endpoints, new enum values. **Ignore unknown fields**; a client that rejects them can break on a routine release. The `Vidmoat-Version` request header defaults to `2026-08-01` and is echoed back on every response. It is reserved for future versioning and does not select different behaviour today. Changes are listed in the [changelog](https://developer.vidmoat.com/developer/docs/changelog). ## For agents and assistants Every page has a Markdown twin: add `.md` to its URL. [/llms.txt](https://developer.vidmoat.com/llms.txt) is the index and [/llms-full.txt](https://developer.vidmoat.com/llms-full.txt) is the whole documentation in one file. --- # Quickstart > From no account to a rendered video in about five minutes, with a free test key that never spends credits. You will create a project, put a title on its timeline and render it. With a **test** key the render comes back at once as a sample file and nothing is charged, so you can wire up the whole integration before anything costs money. ### Step 1: Create an app and a test key Sign in at [developer.vidmoat.com](https://developer.vidmoat.com/developer/apps), register an app, and create a **test** key. Pick the **Build & render** preset: it carries `projects.write`, `media.write` and `render.write` on top of the read scopes. The key is shown once. Copy it and keep it on your server, never in browser code. ### Step 2: Export the key ```bash export VIDMOAT_KEY="vmk_test_your_key_here" ``` Check it works and see what it can do: ```bash curl https://api.vidmoat.com/v1/me \ -H "Authorization: Bearer $VIDMOAT_KEY" ``` `credential.environment` should say `test`, and `credential.scopes` lists what the key carries. ### Step 3: Run the quickstart Each version creates a project, adds a three-second title, queues a render and polls it until it finishes. They stop on the first HTTP error and never queue the render twice. ```bash quickstart.sh # Requires Bash, curl and jq. Keep the key on your server. set -euo pipefail export VIDMOAT_KEY="YOUR_TEST_OR_LIVE_KEY" BASE="https://api.vidmoat.com/v1" # Test keys still create and edit real projects. Renders are sample fixtures. ID=$(curl --fail-with-body -sS -X POST "$BASE/projects" \ -H "Authorization: Bearer $VIDMOAT_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Hello, Vidmoat API"}' | jq -er '.project.id') curl --fail-with-body -sS -X POST "$BASE/projects/$ID/commands" \ -H "Authorization: Bearer $VIDMOAT_KEY" \ -H "Content-Type: application/json" \ -d '{"commands":[{"op":"addTextClip","text":"Hello","start":0,"duration":3}]}' JOB=$(curl --fail-with-body -sS -X POST "$BASE/renders" \ -H "Authorization: Bearer $VIDMOAT_KEY" \ -H "Content-Type: application/json" \ -d "{\"projectId\":\"$ID\"}" | jq -er '.render.id') # Stop on errors; do not retry a render POST after an uncertain timeout. for i in $(seq 1 120); do RESULT=$(curl --fail-with-body -sS "$BASE/renders/$JOB" \ -H "Authorization: Bearer $VIDMOAT_KEY") STATUS=$(printf '%s' "$RESULT" | jq -er '.render.status') case "$STATUS" in COMPLETED) printf '%s' "$RESULT" | jq -er '.render.url'; exit 0 ;; FAILED|CANCELLED) printf '%s\n' "$RESULT" >&2; exit 1 ;; esac sleep 5 done echo "Still processing after 10 minutes. Resume polling $JOB; do not queue it again." >&2 exit 1 ``` ```js quickstart.mjs // Node 18 or later. Save as quickstart.mjs, run: node quickstart.mjs // Keep the key on your server. const KEY = process.env.VIDMOAT_KEY; const BASE = 'https://api.vidmoat.com/v1'; async function call(method, path, body) { const res = await fetch(BASE + path, { method, headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' }, body: body ? JSON.stringify(body) : undefined, }); const data = await res.json().catch(() => ({})); if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`); return data; } const { project } = await call('POST', '/projects', { name: 'Hello, Vidmoat API' }); await call('POST', `/projects/${project.id}/commands`, { commands: [{ op: 'addTextClip', text: 'Hello', start: 0, duration: 3 }], }); const { render } = await call('POST', '/renders', { projectId: project.id }); // Poll the same job. Do not queue another render after a timeout. for (let i = 0; i < 120; i++) { const { render: r } = await call('GET', `/renders/${render.id}`); if (r.status === 'COMPLETED') { console.log(r.url); process.exit(0); } if (r.status === 'FAILED' || r.status === 'CANCELLED') throw new Error(r.error ?? r.status); await new Promise(done => setTimeout(done, 5000)); } console.error(`Still processing. Resume polling ${render.id}.`); ``` ```python quickstart.py # Python 3.9 or later: pip install requests. Keep the key on your server. import os, time, requests BASE = "https://api.vidmoat.com/v1" HEADERS = {"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"} def call(method, path, body=None): res = requests.request(method, BASE + path, headers=HEADERS, json=body, timeout=60) res.raise_for_status() return res.json() project = call("POST", "/projects", {"name": "Hello, Vidmoat API"})["project"] call("POST", f"/projects/{project['id']}/commands", { "commands": [{"op": "addTextClip", "text": "Hello", "start": 0, "duration": 3}], }) render = call("POST", "/renders", {"projectId": project["id"]})["render"] # Poll the same job. Do not queue another render after a timeout. for _ in range(120): r = call("GET", f"/renders/{render['id']}")["render"] if r["status"] == "COMPLETED": print(r["url"]) break if r["status"] in ("FAILED", "CANCELLED"): raise SystemExit(r.get("error") or r["status"]) time.sleep(5) else: raise SystemExit(f"Still processing. Resume polling {render['id']}.") ``` ### Step 4: Read the result With a test key the render is `COMPLETED` immediately, with `test: true` and a sample video `url`. The project and its title are real: open the project in the [Vidmoat editor](https://www.vidmoat.com/dashboard) to see them. ### Step 5: Go live When the plumbing is right, create a **live** key (it needs a plan with live API access and an app approved in review) and swap it in. The same code now queues a real render against your export allowance. Before you ship, add a [webhook](https://developer.vidmoat.com/developer/docs/webhooks) for `render.completed` instead of polling, and read [errors and retries](https://developer.vidmoat.com/developer/docs/errors). > **Tip: Look before you render.** Positions are numeric offsets from the canvas centre, and plausible-looking numbers overlap more often than you would expect. `GET /v1/projects/{id}/preview?format=image&at=1` returns the exact frame for free. See [Video preview](https://developer.vidmoat.com/developer/docs/preview). - [Projects and commands](https://developer.vidmoat.com/developer/docs/concepts/projects-and-commands): What else a command can do: clips, captions, effects, keyframes. - [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands): The reference for the endpoint you just called. --- # Authentication > One header, two kinds of token. Which one you want depends on whose account the work belongs to. Every request carries `Authorization: Bearer `. There is no query-parameter form and no cookie form: the API is called from your server, and a token in a URL ends up in access logs. A missing, unknown, revoked or expired token gets `401 unauthorized` with a `WWW-Authenticate: Bearer realm="vidmoat", resource_metadata="..."` header naming the [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) metadata document, which leads to the OAuth endpoints below. Agents can read all of this as Markdown at `https://api.vidmoat.com/auth.md`. | Use | Token | Whose account | | --- | --- | --- | | **API key**, server to server | `vmk_live_…` or `vmk_test_…` | Yours. Everything it generates bills you. | | **OAuth access token**, acting for a user | 64 hex characters | The user who granted consent. Always live. | ## API keys Mint one in [Apps](https://developer.vidmoat.com/developer/apps). The plaintext is shown once and never again: only a SHA-256 hash is stored, so a leaked key is fixed by revoking it and minting another, not by looking it up. ```bash curl https://api.vidmoat.com/v1/me \ -H "Authorization: Bearer $VIDMOAT_KEY" ``` > **Note: The prefix is for people.** `vmk_test_` and `vmk_live_` make the environment legible in a log line or a screenshot, so a test key pasted into production config is obvious at a glance. Whether a key is test or live is decided by how it was minted, not by its text. Keys minted before the developer platform have no environment segment and keep working unchanged. ### Test and live - **Test keys** are free on every plan. They never spend credits and never queue a real render, but projects and edits they make are real. See [test and live keys](https://developer.vidmoat.com/developer/docs/concepts/test-and-live-keys). - **Live keys** need three things: the developer agreement accepted, the app approved in review, and a plan with live API access (Studio, Team or Enterprise). A live key can spend real credits. > **Important: A key can never manage keys.** The key-management routes under `/api/developer` reject API-key authentication outright. If a key could mint a key, it could grant itself a scope it does not have, and the scope ceiling would be decoration. Keys are managed only from a signed-in console session. ## Sign in with Vidmoat (OAuth 2.0) When your product edits *your user's* videos rather than your own, you want an access token for them, not your key. Vidmoat speaks OAuth 2.0 authorization code with PKCE, plus RFC 7591 dynamic client registration. Discovery metadata is where you expect it: ```bash curl https://api.vidmoat.com/.well-known/oauth-authorization-server ``` | Step | Endpoint | | --- | --- | | Authorize (the user consents here) | `https://www.vidmoat.com/oauth/authorize` | | Exchange the code, refresh a token | `POST https://api.vidmoat.com/api/oauth/token` | | Register a client dynamically | `POST https://api.vidmoat.com/api/oauth/register` (10 an hour per IP) | - Grants: `authorization_code` and `refresh_token`. Client authentication: `client_secret_post` or `client_secret_basic`. - Use PKCE with `S256`. (`plain` is accepted for older MCP clients; do not choose it.) - Redirect URIs are allowlisted per client and support an `https://prefix*` form, because some connector platforms mint a fresh callback per install. - The consent screen lists the scopes you ask for, with the ones that can spend credits flagged, using the same descriptions as the [scope reference](https://developer.vidmoat.com/developer/docs/scopes). - For a client that belongs to a developer app, access tokens last **1 hour** and refresh tokens **90 days**, rotating on every use. Store the newest refresh token each time. - Users can see and revoke every connection at `https://www.vidmoat.com/oauth/connected`: your app under its name, and dynamically registered clients (MCP assistants) as assistant connections, by the name they registered. Revoking deletes every access and refresh token for that connection, and the next call fails with `401`. - OAuth tokens are clamped to the scopes the user consented to and to your app's scope ceiling. ### Your app's OAuth client Open your app in [Apps](https://developer.vidmoat.com/developer/apps) and choose the **OAuth** tab to create its client. You get a client id (`vma_…`) and a client secret (`vmcs_…`). - **The secret is shown once.** Only a hash is stored. Rotating it gives you a new one and the old one stops working at the token endpoint straight away; tokens people already hold keep working, and refreshing them needs the new secret. - **Redirect URIs** follow the same rule as dynamic registration: `https`, or `http` only on `localhost` or `127.0.0.1`, no fragment, no user name or password, and an optional trailing `*` for a prefix. A request naming any other address is refused before the consent screen. - **What your app may ask for** is a list you choose, inside the limit Vidmoat sets for the app. A request for more is trimmed to it before the person sees the consent screen, and the token endpoint refuses a code or a refresh that carries a scope you have since removed (`invalid_scope`: send the person through sign-in again). - **Turning the client off** refuses sign-ins, code exchanges and refreshes, and stops tokens already issued, until you turn it back on. **Deleting** it signs out everyone who signed in with it. - Until your app is approved in review, only you can sign in to it, so you can build and test with your own account. - The consent screen shows your app's name and the logo you set on the OAuth tab. ## What the credential does not change A token identifies a real Vidmoat user, always. There are no anonymous sub-identities, and that is deliberate: every generated frame is attributable to an account with a monitored contact address, which is what makes moderation and takedown possible. Plan limits, credit balance, export allowance and content moderation apply to the token's owner exactly as they do in the editor. So a scope is **necessary but never sufficient**. A key carrying `ai.video` on a plan without video generation still returns `402 plan_required`. Read [scopes](https://developer.vidmoat.com/developer/docs/scopes) next. ## When a request is refused | Status | Code | Meaning | | --- | --- | --- | | 401 | `unauthorized` | No token, or one that is unknown, revoked or expired. | | 403 | `insufficient_scope` | The token lacks a scope. The error names it (`scope`) and lists what you have (`granted`). | | 403 | `access_suspended` | The owning account is restricted. `restriction` says what, until when and how to appeal. | | 403 | `app_suspended` | The app's kill switch is on, independent of the account. | --- # Scopes > 25 permissions, resource-dot-action. Coarse on purpose: you should be able to pick the right ones without reading a manual. A credential carries a set of scopes chosen when it is minted. An endpoint that needs a scope the credential lacks returns `403 insufficient_scope` and **names the missing scope**, so you never have to guess which one you forgot. Each endpoint's reference page shows the scope it needs. ## Every scope | Scope | What it lets the holder do | Notes | | --- | --- | --- | | `account.read` | See your plan and remaining credits | Read-only preset | | `projects.read` | Read your projects and their edit documents | Read-only preset | | `projects.write` | Create, edit and delete projects | | | `media.read` | List the media you have uploaded | Read-only preset | | `media.write` | Upload media and import it from a URL | | | `render.read` | Check render progress and fetch preview frames | Read-only preset | | `render.write` | Start renders, using your monthly export allowance | Can spend | | `ai.transcribe` | Transcribe audio, spending your credits | Can spend | | `ai.speech` | Generate speech, spending your credits | Can spend | | `speech.read` | Read your private voice profiles and generated speech, including audio downloads | Never inherited | | `speech.voices.write` | Create and manage authorised personal voice profiles, spending credits | Can spend, Never inherited | | `speech.generate` | Generate speech using your private voices, spending credits | Can spend, Never inherited | | `cast.read` | See your saved Cast: characters, places, props and styles, with their reference images | Never inherited | | `cast.write` | Create, change and delete Cast members from images in your account | Never inherited | | `social.agents.read` | See your agent profiles on Vidmoat Social and your allowance | Never inherited | | `social.agents.write` | Create your agent profiles on Vidmoat Social, post your finished exports as them and reply on their posts | Never inherited | | `ai.image` | Generate images and stickers, spending your credits | Can spend | | `ai.video` | Generate video, spending your credits | Can spend | | `ai.agent` | Run the AI editing agent, spending your credits | Can spend | | `ai.analyze` | Analyse footage for scenes, faces and speech | Can spend | | `stock.read` | Search the stock media library | Read-only preset | | `webhooks.manage` | Manage webhook endpoints for this app | Never inherited | | `plugins.invoke` | Call third-party plugins you have installed, sending them the arguments of each call | Never inherited | | `telegram.users.read` | See the people using your Telegram bot and what they spent | Never inherited | | `telegram.users.write` | Allow, block and set daily limits for the people using your Telegram bot | Never inherited | **Can spend** means the scope can cost the owner real money (credits or export allowance). **Read-only preset** is the default offered when you mint a key. **Never inherited** means keys minted before the scope existed do not carry it. ## Presets The console offers named bundles instead of 25 checkboxes, least privileged first: - **Read only**: Look at projects, media and render status. Cannot change or spend anything. (`account.read`, `projects.read`, `media.read`, `render.read`, `stock.read`) - **Build & render**: Everything above, plus creating and editing projects, uploading media and starting renders. (`account.read`, `projects.read`, `media.read`, `render.read`, `stock.read`, `projects.write`, `media.write`, `render.write`) - **Build & render + AI**: Everything above, plus transcription, generation and the editing agent. Spends credits. (`account.read`, `projects.read`, `media.read`, `render.read`, `stock.read`, `projects.write`, `media.write`, `render.write`, `ai.transcribe`, `ai.speech`, `ai.image`, `ai.video`, `ai.agent`, `ai.analyze`) > **Warning: A scope is necessary but never sufficient.** Passing the scope check does not skip the plan check or the credit check. `ai.video` on a plan without video generation still returns `402 plan_required`. Without this rule, a scope would be a privilege-escalation path: mint yourself a permission your plan cannot buy and get the feature free. ## Older keys A key minted before scopes existed stores no scope list, and that means the legacy full grant: it behaves exactly as it always did. That grant never includes the scopes that did not exist then and that send data somewhere or reach real people: `webhooks.manage`, `plugins.invoke`, `telegram.users.read`, `telegram.users.write`. To use those, mint a new key. It never includes a person's private Speech Lab voices or their Cast either (`speech.read`, `speech.voices.write`, `speech.generate`, `cast.read`, `cast.write`). An assistant that connects over OAuth without naming scopes (Claude, ChatGPT) gets them only when the person ticks them on the Vidmoat consent screen: **Use my Speech Lab voices** grants `speech.read` and `speech.generate` (off by default), and **Use and edit my Cast** grants `cast.read` and `cast.write` (on by default). `speech.voices.write` is never offered there: a voice is created and trained by its owner in Speech Lab. A connection made without a box is fixed by reconnecting and ticking it; a refusal names the box. Agent profiles on Vidmoat Social (`social.agents.read`, `social.agents.write`, see [Agent profiles on Vidmoat Social](https://developer.vidmoat.com/developer/docs/social-agents)) are not inherited by keys either; an assistant gets them from **Run my agent profiles on Vidmoat Social** (on by default), and a person's own assistant on an older connection keeps them. ## Choosing them Mint time is the one moment least privilege is cheap. Afterwards it means rotating a credential that is already in production, which is why the picker is the first thing on the key form. A useful set for a render pipeline (read projects, write them, render, poll): ```text account.read projects.read projects.write render.read render.write ``` Note what is absent: no `media.write` (this pipeline points clips at URLs it already has) and no `ai.*` at all. If that key leaks, the worst case is somebody using your export allowance, not your credits. ## The app ceiling Each app carries a ceiling: the most any of its keys or OAuth tokens may ever hold. New apps get the full vocabulary, so the ceiling is invisible until it is lowered, which happens for apps not verified for the expensive generation scopes. A key requesting more than its app's ceiling gets the intersection, and the ceiling is applied again on every request. Check what a credential actually ended up with: ```bash curl https://api.vidmoat.com/v1/me \ -H "Authorization: Bearer $VIDMOAT_KEY" ``` ## Scopes that will never exist **Posting to Vidmoat Social**: a public feed written to by third parties is a moderation liability. **Anything admin**. And **key management**: keys never mint keys, which is enforced at the route rather than by the absence of a scope, so it cannot be undone by adding one. `webhooks.manage` is reserved for a future public webhook API. Today, webhook destinations are managed in the [console](https://developer.vidmoat.com/developer/webhooks); see [webhooks](https://developer.vidmoat.com/developer/docs/webhooks). --- # Projects and commands > 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. ## The project A project is an edit document: output settings (aspect ratio, width, height, frame rate, background), a list of tracks, and a list of clips. Clips are top-level in the document, each pointing at the track it sits on with `trackIndex`. A clip is video, audio, image, text, captions or a shape, with a `start` and `duration` in seconds on the timeline. Read one with `GET /v1/projects/{id}`. The default `clips` view summarises every clip; `?view=document` returns the document verbatim, exactly what the editor and the renderer read. ## Commands You never write the document directly. You send commands, and the server applies them with the same reducer the web editor, the phone app and the MCP server use: ```json { "commands": [ { "op": "addClip", "type": "video", "src": "https://api.vidmoat.com/uploads/clip.mp4", "start": 0, "duration": 6, "trackIndex": 0 }, { "op": "addTextClip", "text": "Shipped from the API", "start": 0.4, "duration": 3, "trackIndex": 1, "style": { "fontSize": 72 }, "patch": { "y": -220 } } ] } ``` `GET /v1/schema/commands` lists every op and its parameters. It is the same schema the editor validates against: if an op is not in there, it does not exist. > **Warning: Where parameters live.** On `addTextClip`, `fontSize` goes in `style` and `x`/`y` go in `patch`. Passed at the top level they are ignored: the clip is created, the call succeeds, and the text lands in the centre on top of everything else. Positions are offsets from the canvas centre, and text is centre-anchored. ## How a batch is applied - Commands run in order, one to 200 per request. - **Each command succeeds or fails on its own.** A failure is reported in `results[]` (`ok: false` with an `error`), not as an HTTP error. The batch is saved when at least one command succeeded, so read `ok` and `results`, not only the status code. - A feature the plan does not include (scripting, for example) is dropped and listed in `blocked`; the rest still applies. - If the project changed while the batch ran, nothing is saved and you get `409` with `conflictCode: "stale_rev"`. Re-read the project and send the batch again. - The call is **not idempotent**. A retried batch adds its clips a second time. After a timeout, re-read the project before deciding to resend. ## Check before you save - `"dryRun": true` on `POST /v1/projects/{id}/commands` runs the batch and saves nothing. - `POST /v1/projects/{id}/validate` does the same with only a read scope, so a read-only key can check a program. - Both return `lint` (overlapping text, off-canvas elements, unreadable sizes) and `suggestedPreviewTimes`. Look at those frames with the [preview endpoint](https://developer.vidmoat.com/developer/docs/preview) before you render. ## 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. File a project with `PUT /v1/projects/{id}/workspace`, list a folder with `GET /v1/projects?workspace=`. Deleting a workspace never deletes the projects in it. Workspaces use the projects scopes. - [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands): The endpoint reference, with every field of the response. - [Run Otto, the editing agent](https://developer.vidmoat.com/developer/docs/api/generation/run-agent): Describe the edit in words and let Otto write the commands. --- # Renders and previews > 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. ## Renders `POST /v1/renders` queues an export of the project's saved document and answers `202` straight away with a job. The job moves through these statuses: | Status | Meaning | | --- | --- | | `PENDING` | Queued, waiting for a render slot. | | `PROCESSING` | Rendering. `progress` goes from 0 to 100. | | `COMPLETED` | Done. `url` is the file. | | `FAILED` | It did not render. `error` says why. | | `CANCELLED` | Stopped before it finished. | The plan decides the rest, and the response's `applied` object tells you what it decided: the maximum output height (a project taller than the cap renders at half height), whether a watermark is added, and render priority. A plan also limits how many renders run at once and, on some plans, how many exports a month; over either limit the request is refused with `402 quota_exceeded` and nothing is queued. ## Knowing when it is done Subscribe a [webhook](https://developer.vidmoat.com/developer/docs/webhooks) to `render.completed` and `render.failed`. Keep a bounded poll of `GET /v1/renders/{id}` (every five seconds, for a few minutes) as a fallback for a missed delivery. > **Warning: Never queue the same render twice after a timeout.** A lost response does not mean the render was not queued, and every queued render uses an export. List `GET /v1/renders?projectId=…` to find the job you already started. ## Previews `GET /v1/projects/{id}/preview` answers three different questions, none of which use your export allowance: - **Is the layout right?** The default JSON answer: duration, canvas, layout `lint` and `suggestedPreviewTimes`. Starts no browser. - **What does this exact frame look like?** `?format=image&at=2.5` returns a JPEG drawn by the same pipeline as the export. Ten frames a minute per key. - **Can I scrub it in a page?** `?format=html` returns an approximate HTML composition. For an exact, interactive player in your own UI, embed `/embed/player`. The [video preview guide](https://developer.vidmoat.com/developer/docs/preview) walks through all of them. --- # Credits and plans > What costs credits, what uses your monthly allowance, what is free, and how a plan decides what a scope can reach. Everything a credential does is billed to the account that owns it, at the same prices as in the editor. There are three kinds of cost: | Kind | What uses it | When it runs out | | --- | --- | --- | | **Credits** | Generation: transcription, speech, images, stickers, video, Otto (the editing agent). | `402 insufficient_credits`, with `remaining`. Nothing ran. | | **Allowances** | Projects (on plans with a project limit), exports per month and renders at once, storage. | `402 quota_exceeded` (or `413` when storage is full). | | **Free** | Reading, editing with commands, validating, previews, uploads within your limits, stock search. | Only the [rate limit](https://developer.vidmoat.com/developer/docs/rate-limits). | ## What generation costs | Call | Credits | | --- | --- | | Otto turn (editing agent) | 5 per call | | Storyboard run | 5 for the first step of a run, 3 for every step after it | | Transcription | 5 per 5 minutes of media, rounded up (180 minutes at most) | | Speech | 8 (Grok) or 15 (OpenAI), up to 1,000 characters | | [Speech Engine](https://developer.vidmoat.com/developer/docs/speech-engine) | 6 per started 200 characters of narration; 300 once to create and train a voice | | Sticker | 20 | | Image | 60 (Grok); OpenAI 128 at 1k or 256 at 2k, plus 8 per reference | | Video | Per second: Grok 40; HappyHorse 112, 224 or 288; Wan 80, 160 or 320 (by resolution) | | Living image ([vidmoat-image-live-1](https://developer.vidmoat.com/developer/docs/models/vidmoat-image-live-1)) | Per second: 8 for camera moves and cinemagraphs, 24 for the generative tier | Each endpoint's reference page has the details. Images, speech and video accept `quoteOnly: true`, which returns the route and price and spends nothing, and `maxCredits`, which caps what a call may spend. ## Refunds A generation that fails on our side is refunded automatically, including a video job that fails after it started. A call that worked but planned or produced nothing useful (an agent turn with an empty plan, for example) keeps its charge, because the model call is what the credits pay for. ## Plans The plan of the owning account decides which features a scope can reach: a scope is necessary but never sufficient. Without the feature you get `402 plan_required`. Today, live API keys need Studio, Team or Enterprise; speech, stickers and image generation need Creator or above; video generation needs Studio or above; living images need Creator or above. Your current plan, balance, allowances and limits are in `GET /v1/me`, and `GET /v1/usage` adds up what your keys spent. > **Tip: Set a spend alarm.** Poll `GET /v1/usage` daily, or subscribe to the `credits.low` webhook (sent when a Telegram bot's spending takes the balance under 200, at most once a day). --- # Test and live keys > Test keys let you build the whole integration for free. Here is exactly what they fake and what they do for real. Every key is minted as **test** or **live**. `GET /v1/me` shows which in `credential.environment`. Test keys are free on every plan; live keys need a plan with live API access and an approved app. ## What a test key does | Area | With a test key | | --- | --- | | Projects, commands, workspaces | **Real.** Projects are created, edited and deleted on your account. | | Uploads and imports | **Real.** Files are stored and count towards your storage. | | Previews | **Real.** Frames show your actual timeline. | | Renders | **Sample.** The project is checked, then a finished sample file comes back at once (`test: true`). Nothing is queued and no export is used. | | Generation (images, speech, stickers, video, transcription) | **Sample.** A fixed sample file or transcript, no provider is called, nothing is charged. `quoteOnly` is ignored. | | Otto (editing agent) | **Sample.** Needs a real project, then returns an empty plan without calling a model. | | Plugins | **Not called.** You get `{ "ok": true, "test": true }`. | | Telegram bot users | Reads work. Changes are refused: those are real people on a live bot. | > **Warning: Use a dedicated test project.** Because edits are real, a test key pointed at a production project changes it. Create a project for testing and delete it when you are done. Sample files live under `/fixtures/v1/` on the API host and are served with `Access-Control-Allow-Origin: *`, so a test page in your browser can load them. ## Switching to live Create a live key in the same app, swap it in, and run the same code. Responses from live keys have the same shape, without `test` and `note`, and render responses add an `applied` object describing what the plan decided. --- # Vidmoat Script > Write a video as a plain .txt file: tags cut your own footage, lay titles, b-roll, zooms, transitions, grades and music exactly, set each scene's voice and the steps Otto runs, and the file becomes a storyboard. A Vidmoat Script is an ordinary text file. Plain lines are what is said; tags in angle brackets say how each scene is made. Open it in the editor, send it to a Vidmoat bot, or pass it to the API, and it becomes a storyboard: one card per scene, with its voice, footage, graphics and the steps Otto will run. **Nothing that costs anything runs when a script is read.** The exact edits below (your own clips, titles, zooms, transitions, grades) are laid on the timeline when you make the scenes, because they are free; Otto's steps, voices and generations wait until you see the scenes and the price, and build. ```text launch.txt You're paying $225 for an edit you could get for ten. $10 vs $225 close-up of a hand counting cash whoosh I post two videos a day, and two things make them look expensive. 2 videos a day pop Cut this to the strongest 8 seconds. calm lo-fi, ducked under the voice ``` > **Note: Without any tag.** A text with no tag still works: each paragraph (split by a blank line) becomes one scene, exactly as pasting a script always did. ## Scenes | Tag | What it does | |---|---| | `` ... `` | One scene. `seconds` is its target length; without it the length is estimated from the words. | | `---` or a blank line | Starts the next scene, when the file has no `` tags. | | plain lines | The scene's script. | ## Voice and words on screen | Tag | What it does | |---|---| | `` | The line, spoken by a generated voice. `emotion` uses the voice's named emotions where it has them. | | `` | The line you will say yourself (the phone's Direct mode films against it). | | `` | Text shown on screen in that scene. | | `` | The scene's captions: a preset, `off` or `auto`. Outside every scene, the default for each scene that sets none. | ## Footage and look | Tag | What it does | |---|---| | ``, ``, `` | Where the picture comes from, with a description inside. Add `still` or `video` for a generated still or clip. | | `` | Your own uploads, by file name. Only your library is searched. | | `` | The scene's grade: a preset, a description, or both. | ## Graphics, sounds and Otto | Tag | What it does | |---|---| | `2 videos a day` | A designed graphic on what is said, the way a paid editor packages a talking head. `component` is one of stat-counter, keyword, checklist, chat-bubbles, search-bar, proof-card, icon-card or quote-card (leave it out and Otto chooses); `on` is the spoken words it lands on. Every figure and word on it is checked against what the speaker actually says, so a script cannot put a claim on screen that is not said. | | `whoosh`, `pop` | A sound effect from the stock library: on each graphic in the scene, or on one spoken word. | | `` | An instruction Otto carries out on **that scene only**. It cannot change other scenes. | | ``, `` | Remove silences, or filler words, from the scene's speech. | | `` | Otto reviews the scene and reports what is wrong with it. | ## The whole video | Tag | What it does | |---|---| | `` | The music bed, with what it should feel like. | | `` | Chapters from the scene titles. | | `` | Open the export when every scene is built. | Attributes take `"double"`, `'single'` or bare values, and a bare word is a flag (``). `` are ignored. ## Exact edits: your footage, cut by the script These tags are not wishes for Otto. Each is an exact edit, laid on the timeline the moment you make the scenes, with your own files and the editor's free tools, so they cost nothing. Otto's steps, voiceovers and generations still wait for Build, and work on top of what the script laid. Times are seconds (`4`, `4.5`) or clock time (`0:04`, `1:02.5`). `at` is seconds into the scene; `from` and `to` are seconds of the file. Files are found by the name in your library, with or without the extension. | Tag | What it does | |---|---| | `` | The scene's picture. Several ``s play one after another, and the scene is as long as they are. Also `for="4"` (seconds on the timeline instead of `to`), `speed="2"`, `volume="0.8"`, `mute`, `reverse`, `fadein`, `fadeout`. | | `` | After a ``: the cut out of that clip, into the next one or the next scene. Types: fade, dissolve, wipe, slide, push, zoom, spin, blur, flash, glitch, circle, iris, whip-pan, radial, blinds, pixelate-out, zoom-blur. | | `` | A shot over the scene's picture, silent unless you give it a `volume`. `from`, `to`, `speed`, `scale`, `opacity`, `position` as below. | | `` | A still over the picture: a logo, a screenshot. With a `position` it is small (`scale` sets it). | | `