create_video_from_prompt
ChatGPTClassic Synthesia flow (deprecated): only use it when the user explicitly requests a classic video or the classic flow, or whoami's top-level syren_available is false; else use syren_create_video. 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_script
ChatGPTClassic Synthesia flow (deprecated): only use it when the user explicitly requests a classic video or the classic flow, or whoami's top-level syren_available is false; else use syren_create_video. 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. 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. It is also the path for an EXACT or sub-minute target length: write the script to the length you want. Use create_video_from_prompt when that explicit signal is missing — a topic or brief, or merely ambiguous input. Never guess script on ambiguous input; ask 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, never once per scene: each call creates a separate video. With more than one workspace and none established, this returns needs_workspace_selection and creates NOTHING — ask which workspace, then call again.
delete_draft
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. 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.
generate_video_from_draft
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. 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.
get_brand_context
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. 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_video
ChatGPTClassic Synthesia flow: covers classic videos only, never Synthesia Syren videos (list those with syren_list_videos and open one with syren_show_video). 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_draft_status
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren 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_generation_status
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. 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; never treat as in-progress — if you created this draft, wait until get_video_draft_status reports ready, then call generate_video_from_draft), "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 is wrong, the video was deleted (trash) or archived, or this account can't access it. A never-rendered draft is NOT this — it reports status "not_started" (then call generate_video_from_draft). Check the id/workspace; if the user deleted the draft, create a new one.
list_brand_kits
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. 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_styles
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. 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_templates
ChatGPTPart of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level syren_available is false), never for a Synthesia Syren video. Fetch one page of templates for the "Set up video" widget's picker, or search them by name. Pagination helper for the widget's picker — it lazy-loads more templates as the user scrolls, on both tabs. NOT needed for normal create-from-script calls (get_brand_context already returns the first page of the Synthesia tab, plus its cursor). Returns {templates, next_cursor}; next_cursor is null on the last page, and always null for a search.
list_workspaces
ChatGPTList the user's workspaces. Invoked by the interactive setup widget, not the model. Returns `{workspaces: [{id, name, can_create, plan_tier, capabilities}]} — the SAME workspace entries whoami returns, minus the identity payload around them. The widget calls it to resolve a workspace id when the host hands it no context. It does not read the entitlement fields today: the brand-kit gate it acts on is workspace_brand_kits_available from get_brand_context (DP-1408). They are here so one workspace shape serves both tools. can_create is a role/license permission, NOT a plan check: creating or generating videos also requires a paid Synthesia plan, so a free-plan workspace is refused (plan_forbidden) even where can_create is true. studio_url links to the Synthesia app for this environment, so the widget can offer "Open Synthesia" when the list is empty (a brand-new account still provisioning, MCP-237) without hardcoding a host that differs between dev and prod. It carries the caller's login_hint` like every other link this server hands out (DP-1606), so a user with no browser session lands on their sign-in method rather than the login wall.
search_videos
ChatGPTClassic Synthesia flow: covers classic videos only, never Synthesia Syren videos (list those with syren_list_videos and open one with syren_show_video). Search the user's existing Synthesia video library. Use this to answer questions about videos that already exist — "which videos in the onboarding programme are published?", "what have we made on data privacy?", "show me my recent drafts". Not for creating videos. This is KEYWORD search, not semantic: pass the salient terms from the user's question, not the whole sentence. Results are always scoped to what the authenticated user can access, so videos they can't see in the Synthesia app are never returned. Searches exactly ONE workspace and never aggregates across them, including the user's private "My Videos" space within it — each row's visibility says which. To cover several workspaces, call this once per workspace_id and aggregate the results yourself. With more than one workspace and none established, this returns needs_workspace_selection instead of results — ask which workspace, then call again.
setup_video
ChatGPTClassic Synthesia flow (deprecated): only use it when the user explicitly requests a classic video or the classic flow, or whoami's top-level syren_available is false; else use syren_create_video. Open the interactive video setup widget — the primary entry point for creating an editable classic Synthesia video draft. Requires a paid Synthesia plan: a free-plan workspace is refused and nothing is created. Applies when the client can render web widgets (ChatGPT, Claude desktop): it opens a picker where the user confirms or adjusts the workspace, template and brand kit, then "Create draft" calls the right create_video_* tool for them. Without widgets (a terminal or CLI agent), call create_video_from_prompt / create_video_from_script directly. YOU choose the creation path via mode (or by which of script / prompt you pass) and the user CANNOT change it in the widget, so when it is unclear whether they have a finished script or want one written, ask them BEFORE calling this. Default to "prompt" — treat the input as a brief for the Assistant to develop — and use "script" only when the user explicitly says the text is already written: • "Create a video about the history of Denmark" → prompt • "Turn this slide deck into a video" → prompt • "Here's my finished narration, make a video" → script Call this EXACTLY ONCE per request with the user's COMPLETE input as one string, never per scene: repeat calls render several widgets and create several videos. On "Create draft" the widget runs the create itself, tracks the build and reports the outcome. You get no conversation_id / video_id, so never poll get_video_draft_status for it. The widget shows your selections pre-filled and the user acts on it directly, so keep your reply to one line or nothing. Do not list the workspaces, brand kits or templates, walk through the steps, or offer to adjust the script — that pushes the widget out of view and contradicts what they see.
syren_answer_question
ChatGPTAnswer the question Synthesia Syren's agent is waiting on (state needs_answer), then keep calling syren_get_status with the returned cursor until state is done, needs_answer or halted, and only then tell the user the result. The answer resumes its work; this returns at once and shows the player. Pass option labels in choices, free text, or both. Changes are saved as versions; an earlier one can be restored by asking for it with syren_edit_video.
syren_continue
ChatGPTCarry on a Synthesia Syren turn that stopped short, above all one a status reports as halt_kind: "interrupted" (Syren's server restarted mid-turn) or one halted only because Syren's last edit wasn't checked (halted.reasons just unchecked, so no preview), then keep calling syren_get_status with the returned cursor until state is done, needs_answer or halted, and only then tell the user the result. For those two, call it once without asking the user; for any other halt, only when the user wants to carry on. It sends the director's own resume message (halted.resume), so the agent picks up where it stopped. Returns at once and shows the player. Refused with accepted: false and a reason when nothing is halted: turn_running, question_pending (answer it with syren_answer_question) or not_halted. Changes are saved as versions; an earlier one can be restored by asking for it with syren_edit_video.
syren_create_video
ChatGPTMake a video (up to 3 minutes) with Synthesia Syren (Beta) from a brief, the default for every new video unless the user explicitly asks for a classic video, only when whoami's top-level syren_available is true, then keep calling syren_get_status with the returned cursor until state is done, needs_answer or halted, and only then tell the user the result; don't open a second player with syren_show_video unless the user says they can't see it. A turn often takes 5 to 15 minutes; don't stop early, and if you do, never say the player will update on its own, say they can ask you to check. Syren designs the visuals, on-brand too (put the brand in brief; brand assets can be uploaded in Synthesia Syren); the user edits in the chat. Before the first, tell the user once that Syren is in beta, makes videos up to 3 minutes, uses credits and can't be opened in the classic editor. Then, unless the request already settles it, ask ONE short multiple-choice round on creative direction: an on-screen presenter or not, generated imagery or b-roll clips or motion graphics only, background music and its mood, visual style or palette, length and aspect, each with a default they can accept ("or I can pick for you"). Skip what they already said, never ask a second round, and if they say "just make it", go ahead with sensible defaults. Put the answers in brief: without them Syren's agent makes voice-over and kinetic type only. Later changes go through syren_edit_video with the same conversation_id; to reopen a video use syren_show_video, as this tool always starts a new conversation. A new video goes to the user's My Videos (destination), or the team workspace when that isn't available. If a workspace admin turned Syren off, this says so and offers the classic flow instead.
syren_edit_video
ChatGPTChange a Synthesia Syren video by sending an instruction to the conversation that made it, then keep calling syren_get_status with the returned cursor until state is done, needs_answer or halted, and only then tell the user the result. Every change is saved as a new version and nothing is lost: to undo, call syren_edit_video again with e.g. "undo that" or "go back to the previous version", which restores it as a new version. When the user asks for a look-and-feel change without saying what (a presenter, generated imagery or clips, music, style), offer one short round of concrete options with a default first, then send their pick as the instruction. The agent keeps the whole history. Returns at once and shows the player. While a turn is still running, or the agent is waiting on an answer, the instruction is refused with accepted: false and a reason.
syren_export_video
ChatGPTStart rendering the full-quality video file of a Synthesia Syren video, when the user wants the finished download, then follow it with syren_get_export_status. The file every finished turn gets automatically is a quick preview (video_quality); this renders the video as it is now at its own size and frame rate, which takes render capacity, so only on request. It returns at once: exporting (follow with syren_get_export_status, same arguments; export.phase: waiting when another render of this version goes first), done with video_url when that version is already exported, or failed. Calling it again joins the same render rather than starting another (and repeats a failure of this version), so it is not how to follow it; call it once more only when the status goes from waiting to none, which is when the render starts. available: false with a reason when there is no video yet or this Syren deployment can't export.
syren_get_export_status
ChatGPTCheck the progress of a Synthesia Syren video file export (one syren_export_video started) without starting one, to follow it until done with its video_url. Pass the same arguments as syren_export_video. Returns exporting (with export.phase and export.progress when known; check again in a few seconds), done with video_url, failed, or none when the video as it is now has no export at that quality. If it goes from export.phase: waiting to none, call syren_export_video once more: the render starts then (another render of the same version went first). available: false with a reason when there is no video yet or this Syren deployment can't report it.
syren_get_frame
ChatGPTLook at a Synthesia Syren video at one moment: the frame at at_seconds comes back as an image, for describing or discussing what is on screen there without sending Syren's agent a turn. It shows the video as it is now (its latest revision). available: false with a reason when the conversation has no video yet or this Syren deployment can't render a frame.
syren_get_publish_status
ChatGPTCheck a Synthesia Syren video's Share page without changing anything: how a publication syren_publish_video started is going, or, with no publication_id, what the page shows now and its link. It waits up to about 20 seconds for a publication still going, then returns publishing, rendering or handing_over (still going: check again), published with share_url, failed, or not_published when nothing is on the page. When the video has been edited since that version was published, it says the Share page shows an earlier version.
syren_get_status
ChatGPTWait up to about 15 seconds for Synthesia Syren's agent, then say where it stands: running, needs_answer (a question with options), exporting (the video file is rendering), done (its reply, frames of the video as images, and video_url when exported; the player in this conversation updates itself, so call syren_show_video only if the user says they can't see it) or halted (why it stopped short). Pass back the cursor each call returns, and keep calling until it is done, needs_answer or halted: a turn commonly takes 5 to 15 minutes. If you stop first, never say the player will update on its own; say they can ask you to check.
syren_list_videos
ChatGPTThe videos in a Synthesia Syren workspace, the user's own My Videos and the team's, for having Syren's agent work on one that exists. Each video's location says which: my_videos or team; its conversation_id opens it with syren_show_video.
syren_publish_video
ChatGPTPublish a Synthesia Syren video to a Share page that anyone with the link can watch, when the user asks to publish it or wants a link to share it with other people. It publishes the video as it is now and returns at once, usually publishing: follow it with syren_get_publish_status until it is published, which carries share_url. Publishing the same version again returns its existing publication; after an edit, publishing again updates the Share page, whose link stays the same. Refused while Syren's agent is changing the video (reason: turn_running) and where the workspace's admin has turned publishing off (reason: publishing_disabled). available: false when this Syren deployment can't publish.
syren_report_download
ChatGPTWidget-only: record that the user downloaded the full-quality video file from the player. Analytics only; nothing changes in Synthesia Syren.
syren_report_viewer
ChatGPTWidget-only: tell Synthesia Syren whether the user's player is playing or paused at a moment, so Syren's agent can see where they are; a no-op where Syren doesn't take it.
syren_show_video
ChatGPTOpen the player, without starting a turn or a new conversation, on a Synthesia Syren video from an earlier conversation or session (one the user asks to see, open or show, found with syren_list_videos), or when the user says this conversation's player is missing or broken (they can't see it, or it shows an error); never right after syren_create_video or syren_edit_video in this conversation, whose player updates itself. Pass the conversation_id that made it. Returns where the conversation stands now (as syren_get_status does, without waiting) and the cursor to follow it from.
syren_stop
ChatGPTStop Synthesia Syren's agent mid-turn, when the user asks to. What it already changed in the video stays; the conversation can carry on with syren_edit_video.
syren_unpublish_video
ChatGPTTake a published Synthesia Syren video off its Share page, when the user asks to unpublish it or stop sharing it. Its link stops showing the video; the video itself is unchanged and can be published again. Without a publication_id it takes down whatever the page shows now (not_published when nothing is).
track_widget_event
ChatGPTRecord a setup-widget funnel event for analytics. Invoked by the widget, not the model.
whoami
ChatGPTIdentify the user and list the workspaces they can work in — call this first. Returns the caller's identity plus their workspaces. Every tool call is scoped to ONE workspace (workspace_id) — nothing aggregates across them. Establish the active workspace once from workspaces (auto when there's only one; otherwise ASK the user which to use — do not guess), then reuse that workspace_id for the session unless the user asks to switch. workspaces is [{id, name, can_create, plan_tier, capabilities}] — the team workspaces the user shares with colleagues, which is what "the workspace I'm in" means. plan_tier is "free" / "self_serve" / "enterprise" ("none" = no valid plan, "unknown" = couldn't be resolved); capabilities lists granted feature names such as "brand_kits" (null when unresolved). Both describe THAT workspace's plan — don't offer features its capabilities don't include, and never infer entitlement from data shape (an empty brand-kit list may just be an unconfigured enterprise workspace). can_create reflects role/license, not plan: creating also needs a paid plan (a free-plan workspace is refused). Videos created here land in the user's private "My Videos" WITHIN the chosen team workspace, and search_videos covers it too — the team workspace id is still the one to pass everywhere. If the backend can't be reached this call fails with a retryable error rather than returning an empty list: retry. An empty workspaces carries a note with the cause and the fix; workspace_state names it: no_workspace_yet, should_join (an invitation to accept), awaiting_invite (an admin must invite them) or restricted_access (an admin blocked the app). Top-level syren_available false: Syren is off for this user (admin or outage); never call syren_* tools. Per workspace: whether Syren takes that id. Credits: syren_credit_source is the active pool, "free" (syren_free_credits_left) then "workspace" (syren_workspace_credits); say which (~1,000-2,000 per video minute).
