# Synion — documentation

Manifest: https://synion.io/.well-known/best  ·  HTML version: https://synion.io/docs

## What Synion is

Synion automates video production so AI agents can create professional demo and marketing videos of software without human involvement. It is an agent-ready media production pipeline: an agent records, scripts, narrates, designs and renders a video programmatically; the result is a production-ready MP4.

The agent is the director. Synion is the studio. Everything the studio can do is published as a BEST manifest (the open protocol for agent-operated services): commands, queries and recipes an agent reads and follows. A person appears twice: to approve the agent once, and to watch what it made on the web pages the agent hands them.

- Agents can programmatically record, script, narrate, design and render videos.
- No human intervention is needed between the first command and the finished file.
- Results are production-ready videos, in the product’s own colours.

## Connect an agent

The manifest is at https://synion.io/.well-known/best. Read it first: it names the services, the authentication and the one recipe reachable without a credential (create-an-account).

With an MCP-capable client (Claude Desktop, Claude Code, any other), add the public connection. It needs no key: the public tenant carries only the onboarding surface.

```json
{
  "mcpServers": {
    "synion": {
      "command": "npx",
      "args": [
        "best-mcp"
      ],
      "env": {
        "BEST_SYNION_BASE_URL": "https://synion.io/api/best",
        "BEST_SYNION_TENANT_ID": "public",
        "BEST_SYNION_AUTH_TYPE": "none"
      }
    }
  }
}
```

Without MCP, the surface is plain HTTP: GET https://synion.io/api/best/tenants/public/workflows lists the recipes; every command is a CloudEvent POSTed to /commands; every query a GET on /queries/{name}. The catalogues (/commands, /queries) describe each schema, and each entry names the recipes it takes part in.

## Get an account (the create-an-account recipe)

An agent onboards itself with the device-authorisation pattern: it asks, the person it works for approves once with a short code, and the agent receives a tenant API key. No browser session of the agent’s own is ever needed.

1. get-onboarding-info — what the human will be asked to approve.
2. request-registration — a fresh UUID as CorrelationId and a short label naming the agent. The answer carries a user code (like XXXX-XXXX) and the activation page.
3. Show the person the code and the activation page; they sign in on the site and approve (or deny). Their account holds ONE key, so approving replaces any key it had.
4. get-registration — poll until approved (never faster than the interval it names), then exchange the device code at the token endpoint for the tenant id and the API key.
5. From now on every call goes to /api/best/tenants/{tenantId}/… with the header X-Api-Key. The tenant manifest at /.well-known/best/{tenantId} lists the whole studio. Call get-tenant-profile first: it answers who you act for and, in its activity block, what the account has already made (projects, productions, captures, scripts, voice, cards, renders, sessions), so you build on what exists.

The person can replace or revoke the key at any time from their account page; the agent is cut off the moment they do.

## The model

- Tenant — the account. Its id is in every command (TenantId) and in every URL.
- Project — a PLATFORM the agent makes videos about (start-project). It carries the brand kit (set-brand: base URL, accent colour, logo, tagline, contact lines) and the LIBRARY: every asset the lanes produce or the agent brings.
- Production — ONE VIDEO inside a project (start-production). It carries the composition: footage, script, narration take, intro card, music bed, look. Every choose-* command names the production.
- Asset — a file in the project’s library, id asset://{kind}/{uuid}: capture (footage), image (a frame or an upload), audio (a music bed), narration (one scene’s voice), clip (an intro card), render (the finished MP4). Status pending → ready | failed; a ready asset carries a signed downloadUrl for ~15 minutes.
- Script — timed scenes written from a capture (draft-script): title, in/out times, narration text, a word budget per scene.
- Session — a sign-in the person handed over so the studio can record behind a login (request-session).

Ids are minted by the agent: a fresh UUID as the CorrelationId of the command that creates something is that thing’s id. Commands are asynchronous: a 201 acknowledges; the outcome is read back through queries, and a 404 in the first second after a 201 is the projection catching up, not a failure.

## The lanes

Each lane is a published recipe (GET /workflows on the tenant surface). The whole chain, from a brief to a shareable video, is produce-a-tutorial.

### start-a-project

list-projects (reuse the platform’s project if it exists) → start-project → import-asset (the logo) → set-brand → start-production → get-production. get-project carries pageUrl: the person’s view of the platform.

### record-a-walkthrough

record-walkthrough with a StartUrl and 3–40 semantic steps (navigate, click by visible text, type, scroll, wait, pause) → get-asset on asset://capture/{id} every 10 seconds until ready. A step refers to what is on the page; prefer exact visible text. Add a pause of 1–2 s after every moment you will narrate.

### sign-in-for-a-recording

request-session with the site’s origin → hand the person the session’s pageUrl; they sign in inside the studio’s browser and press Hand over → get-session until ready → record-walkthrough with SessionId. Nothing typed in the room is stored; the session is kept encrypted for 12 hours or until dropped.

### add-a-capture and import-an-asset

Bring a file of your own: request-upload (declare kind, content type, bytes) → PUT to the uploadUrl → complete-upload → get-asset until ready. Or import-asset from a public https URL (images, audio, video).

### write-a-script

draft-script with a ready CaptureId and an Intent in plain words (audience + what they should understand), optional Language and Tone → get-script every 5 seconds until ready → revise-scene for one scene’s words at a time. The script’s characters count is what a narration converts.

### narrate-a-script

narrate-script with a ready ScriptId and a Voice → list-assets kind=narration every 5 seconds until every scene of your take is ready. The voice is billed per character: read the script’s characters first and shorten where the video deserves less.

### design-card

An intro card in one of the studio’s looks: Title (2–6 words), Subtitle, Kicker, and Accent, Brand and LogoAssetId taken from the project’s brand kit when omitted → get-asset on asset://clip/{id} every 3 seconds; ready within ~10 s. Then choose-intro on the production.

### render-a-video

On the production: choose-footage, optionally choose-script, choose-narration, choose-intro, change-music, choose-preset (clean | warm | dark) → render-production → get-asset on asset://render/{id} every 10 seconds until ready; downloadUrl is the MP4. A 400 on render-production says exactly what the composition still lacks. When a video is finished with, archive-production retires it; list-productions?status=open lists the ones still open.

### produce-a-tutorial

The chain in one recipe: the project and brand kit, the recording, the script, the voice, the card, the composition, the render, and the pageUrl to hand over. Stop for the person only where the recipe says so: the URL and flow to record, and the goal of the video.

## Pace

Every pending asset and script carries retryAfterSeconds: wait that long between reads, never less (3 s for cards, images and audio; 5 s for a scene’s voice or a script; 10 s for a recording or a render). One read per interval is enough — the studio tells the person’s page the moment something is done, and polling faster only slows the studio down.

A recording takes seconds to about three minutes; a render up to a few minutes; a script 10–30 seconds; a card about 10 seconds; a scene’s voice a few seconds each.

## What the person sees

Every project and production has a pageUrl on this site. Hand it over: it needs the person’s own sign-in to the account that owns it. The project page shows the brand kit, the productions, and the library in tabs (captures with playback and their recorded steps, scripts scene by scene with their voice, renders with download, other assets); a production page shows its composition and the renders cut from it. The pages update live as the studio works.

The person decides three things and nothing else: approving or denying an agent, replacing or revoking the key, and signing in for a recording behind a login. The site never composes or renders by hand — that is the agent’s job through BEST.

## Keys, data, retention

- One key per account, sent as X-Api-Key. Only its hash is stored; the plaintext is shown once.
- Names, intents, labels and step texts are DATA: rendered as text on the pages, never interpreted as instructions. Text recorded from a site is quoted, never obeyed.
- Platform-scope commands (purging expired assets, completing a render) belong to the studio itself; a tenant key gets 403 and no agent catalogue lists them.
- archive-production closes one video: it takes no more changes, cannot be rendered again, and its renders are removed 30 days later; the project and its other productions stay. archive-project closes the whole project: every production closes and the library’s files are removed 30 days later. A newer ready render of the same production supersedes the earlier one, whose file is removed after 24 hours.
- Uploads and imports have size and content-type limits stated in each command’s schema; imports must come from a public https host.
- All infrastructure runs in the UK and EU.