Developer reference

Synthesys MCP reference

For developers and automation builders: how to connect, how paid tools charge, all fifteen tools, the limits and the errors. It's the same server AI assistants use, on the same account, projects and credits as the Synthesys app. To set up Claude, ChatGPT or another assistant, follow the setup steps for each app instead.

Last updated: October 12, 2026

Server URL: https://mcp.synthesys.io/mcp
Transport: Streamable HTTP
Sign in: OAuth, or an API key

Authentication

Connect

Every client uses the same endpoint, named synthesys. Assistants sign in with a Synthesys account. Automations that can't open a sign-in window send an API key.

Sign-in, for AI assistants

Apps that support remote MCP servers with sign-in find the Synthesys sign-in page from the URL (OAuth) and open it for you. There is nothing to copy, and Synthesys never sees your password: it gets an access token from our sign-in provider. Steps for Claude, ChatGPT, Cursor, Claude Code, Codex and VS Code are on the Synthesys MCP page.

MCP URL

https://mcp.synthesys.io/mcp

API key, for automations

Send your key on every request. Create keys in Synthesys under Manage Account → API keys. A key is shown once, acts only on your own account and can be revoked at any time. A revoked key stops working within a minute. We store only a hash of each key, so a lost key can't be shown again: revoke it and create a new one.

Header

Authorization: Bearer <API key>

Billing

How paid tools work

All prices are in credits, where 100 credits equal $1, at the same prices as the app. Apart from a clip without a chosen model, nothing that costs credits happens in one call.

01
Ask for a quote
Call create_video with a brief, or generate_image or generate_clip with a model, and leave out confirm. You get state: "quote_ready" and the price in credits. Nothing is spent.
02
Get a yes
Show the price to the person paying and wait for them to accept it. The tools tell assistants never to confirm without an explicit yes.
03
Confirm
generate_image and generate_clip: the same inputs plus confirm: true, the quote_id and quoted_credits (the price that was shown). create_video: the project_id and confirm: true. confirm: false declines and spends nothing.

One quote, one charge: A quote_id is valid for 30 minutes and is tied to your account, the exact inputs and the price. If a confirm errors or times out, send it again with the same quote_id: you get the same run back instead of a new charge. Asking for a new quote starts a new run. One rare exception: an image retried just after a Synthesys update can run again, so check list_files before retrying a long-finished image.
If the price changed: A confirm with an expired quote, different inputs or a quoted_credits that doesn't match returns state: "quote_changed" with the current price and a fresh quote_id. Nothing is charged.
Clips without a model start at once: generate_clip without a model starts on the first call and costs roughly 40 to 50 credits a second, about 200 for 4 seconds. The response includes an approximate cost, and the finished status reports what was charged.
Ad recreation: recreate_from_url charges 10 credits for the analysis, only when it succeeds. The production is then quoted, and nothing renders until create_video is called with its project_id and confirm: true.
Charged on success: A clip from a chosen model is charged when it's delivered, and an image that fails costs nothing. A call refused for credits or the daily limit is refused before any work starts.
Long jobs return a handle: Videos and clips return a project_id straight away. Follow them with get_video_status every 30 to 60 seconds.

Tools

The fifteen tools

Every response includes a next field: a plain-language instruction for what to do next. Tools that take an aspect ratio accept 16:9, 9:16, 1:1, 4:5, 21:9, 9:21, 4:3, 3:4, though a chosen image or clip model may offer fewer.

Videos

create_video

Quote first

Plans and builds a full video from a brief: script, scenes, voiceover, presenters, captions, music and the edit. It works in two steps, so it can't spend in one call.

Inputs: briefrequired Step 1. What to make: product, audience, hook, tone and any lines to include.
template A key from list_templates. Leave it out and Synthesys picks the format.
duration_seconds Target length, 5 to 600.
aspect_ratio One of the supported ratios.
reference_asset_urls asset_url values from upload_reference, list_files or generate_image.
actor_id, voice_id, brand_kit_id From list_actors, list_voices and list_brand_kits. Leave them out and Synthesys chooses.
no_people true for nothing human on camera, hands included. Not with templates that always show a person.
project_id, confirm Step 2. confirm: true accepts the quote and starts the production. confirm: false declines and spends nothing. project_id on its own only reads the status.
Returns: Step 1: project_id, state: "quote_ready" and quote (scenes, seconds, credits). Step 2: state: "production_started". Follow it with get_video_status.
Cost: Planning and the quote are free. Nothing is spent until confirm: true. Quote in 30 to 90 s, production usually 10 to 25 min.

recreate_from_url

10 credits

Analyses an ad from a public link and plans your version of it. With mode: "page" it turns a product, landing or app store page into an ad instead.

Inputs: urlrequired A direct video file, an ad page with a video, or a TikTok, Meta or YouTube link. A product page with mode "page".
notes Your product or brand, and what to change from the original.
mode "ad" (default), "page" or "auto".
Returns: project_id, the analysis (hook, beats, pacing, visual style, call to action and transcript) or the captured page, and a quote for the production.
Cost: 10 credits for the analysis, charged only when it succeeds. The production is quoted and needs create_video with confirm: true. Analysis 1 to 3 min, longer for page links. Recreates run up to 60 s.

get_video_status

Free

Reports where a video or clip is: building, waiting for a decision, finished or stopped.

Inputs: project_idrequired From create_video, recreate_from_url or generate_clip.
Returns: state (rendering, awaiting_confirmation, awaiting_review, awaiting_approval, awaiting_answer, complete or error), scene progress, the quote, any pending question or approval, and video_url with the credits spent once complete.
Cost: Free. Poll every 30 to 60 s.

answer_question

Free

Sends an answer when a build pauses on a question, so it carries on from where it stopped.

Inputs: project_idrequired The paused project.
question_idrequired From pending_question in get_video_status.
answer or skip The answer, or skip: true to let Synthesys decide.
Returns: ok: true when the build resumes. If the question changed in the meantime, state: "question_changed" with the new question to answer.
Cost: Free.

Clips and images

generate_clip

Paid

Renders one 4 to 15 second clip from a prompt: a product shot, b-roll or a one-scene ad.

Inputs: promptrequired Subject, action, look and camera.
duration_seconds 4 to 15, default 8.
aspect_ratio, template, reference_asset_urls, no_people As in create_video. The default template shows the product, not people.
model A model_id from list_models. Makes the call quote first. Use resolution and start_frame_url (a picture to animate) with it, not template or references.
confirm, quote_id, quoted_credits With a model, after the quote is accepted.
Returns: project_id to follow with get_video_status, and an approximate cost. With a model, the first call returns state: "quote_ready", the exact price and a quote_id.
Cost: Without a model it starts at once: roughly 40 to 50 credits a second, about 200 for 4 s. With a model it's quoted first and charged when the clip is delivered. Usually 8 to 13 min.

generate_image

Quote first

Creates images from a prompt, or edits one of yours, with the model you pick.

Inputs: promptrequired What the image shows, or what to change.
model A model_id from list_models. Leave it out for the default.
aspect_ratio, resolution One the model offers.
images 1 to 4 per run. The price scales with it.
reference_asset_urls, edit Images to guide the result, or the image to edit with edit: true.
confirm, quote_id, quoted_credits After the quote is accepted.
Returns: First call: state: "quote_ready", the exact price and a quote_id. After the confirm: state: "complete" with each image's asset_url and spent_credits.
Cost: Exact price first. An image that fails isn't charged. Seconds to about 2 min. Images are saved to your library.

list_models

Free

Lists the image or video models you can choose, with their maker, aspect ratios, resolutions, clip lengths and exact prices.

Inputs: categoryrequired "image" or "video".
aspect_ratio Price the models at this ratio.
duration_seconds Video only, 4 to 15.
images Image only, 1 to 4.
Returns: models, each with model_id, name, maker, options and the price in credits per resolution.
Cost: Free.

Your material

upload_reference

Free

Brings an image or video from a public link into Synthesys so a build can use it.

Inputs: urlrequired A public http(s) link.
filename A name to store it under.
Returns: asset_url to pass in reference_asset_urls, and asset_type (image or video).
Cost: Free. A few seconds.

create_upload_link

Free

Gives you a short-lived page to add images or videos from your device. Files attached in a chat don't reach connected tools, so this is how local files get in.

Inputs: None.
Returns: upload_url, expires_at and the limits. After the upload, find the files with list_files.
Cost: Free. Each link works for 30 minutes and up to 10 files.

list_files

Free

Lists the images and videos in your Synthesys library, newest first.

Inputs: type "image" or "video".
query Filter by file name.
limit, offset 1 to 100, default 30. Pass next_offset to page.
Returns: files, each with asset_url and preview_url, plus total and next_offset when there are more.
Cost: Free.

list_actors

Free

Lists who can be on camera: your own digital twins first, by name only, then stock actors with a preview.

Inputs: query Filter by name.
gender "male" or "female".
limit, offset 1 to 60, default 24. Pass next_offset to page.
Returns: actors, each with actor_id, name and kind. Stock actors also have preview_url.
Cost: Free.

list_voices

Free

Lists the voices that can narrate: your own cloned voices first, then the voice library, each with an audio sample.

Inputs: query Filter by name or style, for example "warm".
Returns: voices, each with voice_id, name, style and preview_url.
Cost: Free.

list_brand_kits

Free

Lists your Brand Kits and which one is active. Pass one to create_video for your logo end card, colours, fonts, tagline and call to action.

Inputs: None.
Returns: brand_kits with brand_kit_id, and available: false on plans without Brand Kit, which comes with Pro and up.
Cost: Free.

Account

get_credits

Free

Shows your balance, what's left of today's limit, the price list and recent usage.

Inputs: None.
Returns: balance, daily_cap, spent_today, in_flight_credits, remaining_today, price_schedule and recent_usage.
Cost: Free.

list_templates

Free

Lists every video format and visual style. Call it first to pick a template key and a length that fits.

Inputs: None.
Returns: templates, each with its name, default and maximum length, aspect ratio and styles. To use a style, name it in the brief.
Cost: Free.

Limits

Limits and timings

Daily limit: 5,000 credits ($50): Shared by connected apps and API keys. It counts everything the account spent that day, including in the web app, plus credits held by builds still running, and resets at 00:00 UTC. At the limit, calls that could spend are refused before anything runs. Status checks, get_credits and upload links keep working, and the web app is never blocked.
Upload links: 30 minutes, 10 files: Images up to 50 MB (PNG, JPG, WEBP, GIF, AVIF) and videos up to 300 MB (MP4, MOV, WEBM). The page needs no sign-in and can only add files to the account that made the link.
Quotes: 30 minutes: After that, a confirm returns a fresh quote instead of charging.
Sessions: An idle session closes after 10 minutes. Start a new one with initialize. MCP SDKs do this for you.

How long things take

What	Usually takes	Check status
Lists and credit checks	Under 2 s (actors: a few seconds)	—
Bringing in a file from a link	A few seconds	—
Video quote (create_video)	30 to 90 s	Every 10 to 15 s if it returns "planning"
Ad analysis (recreate_from_url)	1 to 3 min, longer for page links	—
Image	Seconds to about 2 min	—
Clip	8 to 13 min	Every 30 to 60 s
Full production	Usually 10 to 25 min. Don't give up before 30	Every 30 to 60 s

Troubleshooting

Errors

The endpoint answers with an HTTP status for sign-in, session and rate limit problems. Errors inside a tool come back as a tool result with isError: true and a plain-language message that says what to do, so an assistant can pass it on as it is.

401
The API key is missing, wrong or revoked.
Create a new key in Manage Account → API keys and update the Authorization header. Sign-in apps: a 401 with a WWW-Authenticate header on first connect is normal. It's how they find the sign-in page.
402 daily_cap
Today's limit for connected apps and API keys is reached.
Wait for the reset at 00:00 UTC, and don't retry in a loop: the limit is checked before anything runs. get_credits shows remaining_today.
402 insufficient
Out of credits. The balance won't cover the step, and nothing was charged.
Add credits in the Synthesys app with a plan or a credit pack, then confirm again.
402 too_many_running
Too many videos are already building on the account.
Wait for one to finish, then retry. Adding credits won't help.
quote_changed
A confirm couldn't run as sent: the quote expired, the inputs changed or the price is different. Nothing was charged.
Show the new price and confirm with the fresh quote_id.
429
Too many requests, or too many open sessions.
Wait about 60 seconds, or the Retry-After seconds, and slow down. Polling every 30 to 60 seconds stays well inside the limits. Close sessions you no longer use.
404 Session not found
The mcp-session-id was closed or expired.
Start a new session with initialize.

Example

Try it with curl

The raw protocol, for testing an API key or wiring up a tool without an MCP SDK. An SDK does these steps for you: point its Streamable HTTP client at the URL and add the Authorization header.

1
Set your key
read -s waits for you to paste your API key and press Enter, and keeps the key out of your shell history.
Terminal
```
MCP=https://mcp.synthesys.io/mcp
read -s KEY
```

Start a session

The reply's mcp-session-id header names the session. This keeps it in SESSION for the next calls. If it prints nothing, run the curl on its own to see the error.

Terminal

SESSION=$(curl -si -X POST "$MCP" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-script","version":"1.0"}}}' \
  | grep -i '^mcp-session-id:' | awk '{print $2}' | tr -d '\r')
echo "$SESSION"

Say the client is ready

The protocol expects this notification after initialize. It answers 202 with no body.

Terminal

curl -si -X POST "$MCP" \
  -H "Authorization: Bearer $KEY" \
  -H "mcp-session-id: $SESSION" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

List the tools

Returns all fifteen tools with their input schemas.

Terminal

curl -s -X POST "$MCP" \
  -H "Authorization: Bearer $KEY" \
  -H "mcp-session-id: $SESSION" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Call get_credits

Free, so this costs nothing. The result is your balance, what's left of today's limit and the price list.

Terminal

curl -s -X POST "$MCP" \
  -H "Authorization: Bearer $KEY" \
  -H "mcp-session-id: $SESSION" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_credits","arguments":{}}}'

Replies arrive as server-sent events: the JSON is on the line that starts with data:. A 404 on a later call means the session closed, so start again with step 2.

Setting up an assistant?

The Synthesys MCP page has the steps for each app, what your assistant can see, how to disconnect and fixes for common problems.

Need help?

Search the Synthesys help center or email support@synthesys.io. Include the tool, the time and the message you got.

Connect

Sign-in, for AI assistants

API key, for automations

How paid tools work

Ask for a quote

Get a yes

Confirm

The fifteen tools

Videos

create_video

recreate_from_url

get_video_status

answer_question

Clips and images

generate_clip

generate_image

list_models

Your material

upload_reference

create_upload_link

list_files

list_actors

list_voices

list_brand_kits

Account

get_credits

list_templates

Limits and timings

How long things take

Errors

Try it with curl

Set your key

Start a session

Say the client is ready

List the tools

Call get_credits

Setting up an assistant?

Need help?