Synthesia

Create a Synthesia video draft from a PROMPT where no widget can be shown; on Claude and ChatGPT, `setup_video` covers this flow. Requires a paid Synthesia plan: a free-plan workspace is refused and nothing is created. For a terminal or CLI agent, and for programmatic callers. Use this when the user gives an idea, topic, or brief rather than the exact words to be spoken ("make a short explainer about our refund policy"), and whenever it is merely ambiguous which of the two they have. The Assistant outlines from the prompt, writes the narration itself, and builds a multi-scene draft. Use `create_video_from_script` instead only when the user explicitly says the text is already written; ask them rather than guessing when that is unclear. Template and brand kit fall back to the workspace defaults unless you pass `template_id` / `brand_kit_id`, which `get_brand_context` can ground. `design_mode: "auto"` instead lets Synthesia compose the video with no template, and the result then reports `design_mode: "auto"` with a null `template_id`. `style_id` applies one of Synthesia's own styles; it replaces `brand_kit_id` and `template_id` rather than combining with either, so passing it alongside one of those is rejected. Returns immediately with identifiers and a Synthesia app link while the draft builds in the background; poll `get_video_draft_status` until its status is "ready". Call this ONCE per video: the Assistant produces every scene from the single prompt, so never call it once per scene. With more than one workspace and none established, this returns `needs_workspace_selection` and creates NOTHING — ask which workspace, then call again.

create_video_from_prompt

Create a Synthesia video draft from an EXISTING script where no widget can be shown; on Claude and ChatGPT, `setup_video` covers this flow. Requires a paid Synthesia plan: a free-plan workspace is refused and nothing is created. For a terminal or CLI agent, and for programmatic callers. Use this only when the user explicitly says the text is already written — a finished script, transcript, or narration ("here's my script", or they paste one). The script is imported VERBATIM: the Assistant splits it into scenes on a workspace template and copies the text into each scene's narration without rewriting, paraphrasing, shortening or expanding it. Use `create_video_from_prompt` whenever that explicit signal is missing — a topic, brief or idea to develop, and any case where it is merely ambiguous which the user has. Never guess script on ambiguous input; ask them first. Template and brand kit fall back to the workspace defaults unless you pass `template_id` / `brand_kit_id`, which `get_brand_context` can ground. `design_mode: "auto"` instead lets Synthesia compose the video with no template, and the result then reports `design_mode: "auto"` with a null `template_id`. `style_id` applies one of Synthesia's own styles; it replaces `brand_kit_id` and `template_id` rather than combining with either, so passing it alongside one of those is rejected. Returns immediately with identifiers and a Synthesia app link while the draft builds in the background; poll `get_video_draft_status` until its status is "ready". Call this ONCE with the complete script: the whole script becomes ONE video and the Assistant segments it. Never split it into scenes or call this once per scene — that would create several videos. With more than one workspace and none established, this returns `needs_workspace_selection` and creates NOTHING — ask which workspace, then call again.

create_video_from_script

Delete a DRAFT video, never a published one, archiving it to the Synthesia app's trash. Useful for clearing up drafts created during a session. Guarded: fetches the video first and refuses it unless it is a draft AND has no published version — so a draft that has already been published once is refused too, and published or shared videos are never removed here (delete those in the Synthesia app if intended). Archiving rather than erasing matches the app's own delete action. Three distinct results, so a refusal is never confused with a failure: `{deleted: true, video_id}` succeeded; `{deleted: false, refused: true, is_draft, published, reason}` the guard blocked it; `{deleted: false, error: true, detail}` the lookup or the delete itself failed.

delete_draft

Start rendering a draft into a watchable video — this SPENDS the workspace's video credits, so call it only when the user has explicitly asked to generate or render. Requires a paid Synthesia plan: on a free-plan workspace the render is refused, with no render started and no credits spent. Rendering is the separate, credit-spending step after drafting: create_video_from_script / create_video_from_prompt build the editable draft for free, and this turns the draft's current snapshot into an actual video. Never call it to "finish" a draft build, to retry a slow poll, or speculatively — an unwanted call costs real credits. When it is unclear whether the user wants the render, ask first. The draft should be ready first (get_video_draft_status "ready"). A draft the Assistant is still building (or whose build failed) is refused before any credits are spent, as is a draft with problems that block generation — the refusal says why. Returns {status: "generating", video_id, version, studio_url} immediately while the render runs in the background. `version` names THIS render — pass it to get_video_generation_status and poll until "complete" or "failed" (renders take minutes). On failure returns {error: true, detail}; the detail states whether a render was started. The rendered video stays private; publishing is in the Synthesia app.

generate_video_from_draft

List a workspace's brand kits and templates for video setup. `workspace_brand_kits_available` says whether the workspace's plan includes brand kits at all: when false the kit fields are empty and a create for that workspace must not pass `brand_kit_id` — templates still work as normal. When true, an empty `brand_kits` just means none are configured yet. `brand_kits` is only the FIRST page (workspaces can have hundreds — the full list can exceed the host's 1MB tool-result cap). `brand_kit_count` is the total and `brand_kits_next_cursor` is non-null when more exist and pages through `list_brand_kits`. Prefer `list_styles` for new work — it covers these kits AND the curated catalogue in one list, with its own cursors. The default brand kit is always on this first page. `styles` (absent when unavailable) is the first page of the curated Synthesia catalogue — read-only public brand kits, NOT this workspace's own kits in `brand_kits`; each carries `scope: "synthesia"`, and `styles_next_cursor` pages the rest via `list_styles(scope="synthesia")`. A create can't apply one yet: `brand_kit_id` takes this workspace's own kits only and rejects a style id. `templates` is likewise the first page of the Synthesia (stock) tab; page the rest with `list_templates(source="synthesia", cursor=templates_next_cursor)`. `default_template_id` (with `default_template` carrying its title/thumbnail) is the template a create defaults to when none is passed — the workspace's or org's configured default, else the top stock template. Name it when offering the default rather than calling it just "the default". With more than one workspace and none established, this returns `needs_workspace_selection` and no lists — ask which workspace, then call again.

get_brand_context

Get full metadata for a single video by id. Use after search_videos (or when the user names a specific video) for richer detail than the search rows: title, description, render status, draft/published state, duration, owner, template, workspace, thumbnail, timestamps, and a Synthesia app link. `render_status` is "not_started" (never generated — generate_video_from_draft starts a render) or the backend's raw UPPERCASE render state (IN_PROGRESS, COMPLETE, ERROR). `visibility` says who can see it ("private" = only this user's My Videos, "workspace" = the team); `workspace_id` is always the TEAM workspace id, also for private videos.

get_video

Check whether a draft started by create_video_from_script / create_video_from_prompt has finished building — the DRAFT build only, not the rendered video. Returns status 'building', 'ready', or 'error'. When ready, includes the Assistant's last message (so build failures aren't silent) and `applied_style_id`: the branding actually on the draft, at whatever scope, so a Synthesia style and a workspace brand kit both appear here. Compare it against the `style_id` the create tool echoed back to tell an applied selection from a silently dropped one; both are the bare uuid, so strip any `library.` prefix before comparing an id you supplied yourself. Absent means it couldn't be read, which is not the same as null. When ready, `assets_ready` (when present) says whether generated media has finished preparing; wait for `assets_ready: true` before generate_video_from_draft, which is refused while assets prepare. Absent means it couldn't be checked — treat as ready.

get_video_draft_status

Check progress of a RENDER started by generate_video_from_draft — the video generation lifecycle, not the draft build (that is get_video_draft_status; the two share no statuses). `status` is "not_started" (NO render exists yet — generate_video_from_draft starts one; never treat as in-progress), "queued", "rendering" (`stage` may name the step: moderating, preparing, rendering, assembling, finalizing), "complete", or "failed" (terminal; `failed_reason` when known). `progress` is 0-1 and may move BACKWARD on a retry — normal, not an error; only "complete" and "failed" are terminal, and `retrying: true` means keep polling. `in_manual_review: true` freezes progress for a human review, possibly hours — tell the user rather than poll tightly. `eta_seconds` is a rough estimate (absent once exhausted — expected, not failure); trust `progress` over it and keep polling. Poll every ~5 seconds or slower. On "complete" the payload adds `studio_url` (watch page), the render `version`, and signed, short-lived playback URLs — `playback_url` (what to play; the `source_url` mp4 for this server's drafts), `source_url`, `mux_url` (usually absent), `subtitles_url`, `duration_seconds`, `chapters`. Never store them; on a playback error poll again. {error: true, not_found: true} means this video/version has no readable render: the id or version may be wrong, the video deleted — or the render FAILED terminally (the backend reports these identically). If you started this render yourself moments ago, treat not_found as a failure and point the user at the video in the Synthesia app.

get_video_generation_status

DEPRECATED — use `list_styles`. Pages a workspace's own brand kits only. Returns `{brand_kits, next_cursor, workspace_brand_kits_available}`; `next_cursor` is null on the last page. `workspace_brand_kits_available` false means the workspace's plan doesn't include brand kits (the list is empty and creates must not pass `brand_kit_id`), not that none exist.

list_brand_kits

Page through or search one source of Styles (get_brand_context returns only page 1). A Style is a look: fonts and colours. `scope` picks the source and every row echoes it back. Returns `{styles, next_cursor}`; `next_cursor` is null on the last page and is an offset into THIS scope and query, so don't replay it against another. `scope: "synthesia"` is the curated catalogue every user can pick, whatever their plan. The owned scopes also return `workspace_brand_kits_available`; false means the workspace's plan doesn't include brand kits, so the list is empty and creates must not pass `brand_kit_id`.

list_styles