Frameo

npx add-mcp 'https://mcp.frameo.ai/mcp'

The Model Context Protocol server that lets AI assistants create with a user's Frameo account. This page is generated from the server's live tool list.

Endpoint

Server URL	https://mcp.frameo.ai/mcp
Transport	Streamable HTTP (MCP)
Authentication	OAuth 2.1 with PKCE (S256), scope frameo

Connecting

Client	How
Claude	Settings → Connectors → Add custom connector, and paste the server URL.
ChatGPT	Add a custom app in Settings → Apps, and paste the server URL.
Claude Code	claude mcp add --transport http frameo https://mcp.frameo.ai/mcp
Cursor	Add to mcp.json: {"mcpServers": {"frameo": {"url": "https://mcp.frameo.ai/mcp"}}}

On the first call the client opens Frameo's sign-in page. The user signs in with their Frameo account, picks the workspace the connection starts in, and approves. switch_workspace later moves the connection to any other workspace the user belongs to. Disconnecting the connector in the client, or revoking it, ends access.

Directories

The Frameo MCP server is listed in:

• Smithery

Authorization

Clients discover everything from the protected-resource metadata; no client secret is issued, and every client is public and uses PKCE.

Protected resource metadata	https://mcp.frameo.ai/.well-known/oauth-protected-resource/mcp
Authorization server metadata	https://mcp.frameo.ai/.well-known/oauth-authorization-server
Authorize	https://mcp.frameo.ai/authorize
Token	https://mcp.frameo.ai/token
Dynamic client registration	https://mcp.frameo.ai/register
Revocation	https://mcp.frameo.ai/revoke

Client ID metadata documents are accepted in place of registration.

Overview

Frameo is an AI video production platform for short films, micro-dramas, ads and social video: images, video clips, voiceovers, music and sound effects are generated on a project's canvas, kept consistent from shot to shot, and assembled into the final cut. Frameo has a skill for almost every kind of job, from a script into a video to a UGC ad or a photoshoot, and skills give the best results. For multi-step work, list_skills finds the right one and get_skill returns the steps to follow from the start. Work is organised as workspace → project → module, and each module has its own canvas, chat and Library. This connection works in one workspace at a time. What this connection makes is recorded in the module's chat and Library, and placed on its canvas once the project is open in the app. How a job goes: 1. whoami: the workspace this connection works in, its credits, and the user's other workspaces. 2. list_projects or create_project (create_module adds one module to the project): the project_id and module_id every tool making something takes. 3. list_skills, then get_skill: the steps for the job. 4. estimate_cost, then a generate tool (generate_image, generate_video, generate_speech, generate_music, generate_sound_effect, generate_lipsync, upscale_video): the quote_id is single-use, valid for 15 minutes and bound to those settings; the generate call redeems it with confirmed_by_user once the user agrees, and a call that differs is refused uncharged. 5. show_generations and wait_task: in chat apps that show cards, the user sees the work only on a show_generations card, and without one sees nothing for what can be tens of minutes. One card per wave: every id started before the next wait_task, shown before it; final true for the finished result. wait_task collects the results. Choosing the tool: - Files on the user's device: show_upload. A web link: import_media_url. - Titles, captions and text on a video: render_motion_graphics or run_ffmpeg, not a video model. - Brightness, colour, crop, speed or length of existing media: run_ffmpeg. A change to what is in it: a new generation. - A voiceover: generate_speech. A person speaking on screen: generate_speech, then generate_lipsync when their mouth has to match the words. - The user's own clips: analyze_media reports what is in them before they are edited. - A sharper video: upscale_video (videos only). - A problem with Frameo, or something it cannot do yet: report_problem. Consistency: a recurring character or product stays the same when its earlier images are passed as references (image_urls, reference_image_urls) or saved with save_character. Checking results: wait_task returns small previews, so a result can be checked against the request before it is built on. The review-shots skill checks a whole set of shots and the finished cut, and retakes a failed shot once; a retake is quoted like any other generation. Shapes: 9:16 for Reels, TikTok and Shorts; 16:9 for YouTube; 1:1 or 3:4 for feed posts, where the model takes them (list_models). Thumbnails and covers: a new image (the thumbnail-set skill); a video has no cover setting. Without credits: uploads, imports, run_ffmpeg, render_motion_graphics, search_sound_effects and every read still work.

Errors

A tool that fails returns a result rather than a protocol error. error is a stable code, hint says what to change, and retryable says whether the same call may succeed later. A failed paid call states whether work started and what was charged.

{
  "ok": false,
  "error": "quote_mismatch",
  "hint": "These settings differ from the quoted ones (differs lists each). Nothing was charged, and the quote_id is still valid for its original settings; estimate_cost with the new settings returns a quote for them.",
  "differs": {"resolution": {"quoted": "480p", "requested": "720p"}},
  "retryable": false
}

Tools (43)

Writes · free

Save a library sound to a project

Save a sound from search_sound_effects into a project's Library. Free: nothing is generated. The sound is saved to the project's Library.

Argument	Type	Default
sound_id	string	required
project_id	string	optional
module_id	string	optional
request_text	string	optional

Writes · free

Add an upload to the project's Library

Put a file uploaded through create_upload_url into a project's Library. Free. The stored file is checked first: it must exist, be within the size limit for its kind (images 20 MB, video 200 MB, audio 50 MB), and be stored with a content type of that kind. Adding the same file to the same module again changes nothing, its name included, and reports ok. Returns ok, frameo_url, kind and open_in_frameo, a link to the project.

Argument	Type	Default
frameo_url	string	required
project_id	string	optional
module_id	string	optional
name	string	optional

Uses credits

Analyze a video or audio clip

Describe or transcribe a video or audio clip that is in Frameo. Uses credits, charged by clip length once it has run — the one paid tool with no quote. The answer comes back as text and is also recorded in the project's Frameo chat. The price is not knowable before the run: it is a few credits per minute of media. confirmed_by_user records that the user was told that and agreed; without it the call is refused. The finished run's result (wait_task / get_task) carries credits_charged_estimate, the wallet's change while it ran (null on a poll that came before the charge landed). Returns a run id for wait_task. Usually done within a minute. In one module these runs (ffmpeg, motion graphics, media analysis) go one at a time: while one is in progress, another started in the same module is refused with chat_busy, which is retryable. Other modules are unaffected, and generate tools in the module still run.

Argument	Type	Default
media_url	string	required
question	string	required
project_id	string	optional
module_id	string	optional
confirmed_by_user	boolean	False

Writes · free

Open Frameo signed in

Make a one-time link that opens a page of the Frameo web app signed in as this connection's user and in its workspace, for the Open in Frameo button on a result card. Free. Returns url, a Frameo link that signs in once and within 60 seconds; after that it still opens the destination, without signing in. Each connection makes up to 10 a minute.

Argument	Type	Default
destination	string	required

Writes · free

Add a module to a project

Add a module, with its own canvas, chat and Library, to an existing project. Free. A project from create_project already has its first module. Returns the new module's module_id, which every generate tool takes, its module_number (one more than the project's highest, the order the app lists modules in) and an open_in_frameo link to it. Several calls for one project sent together are numbered in the order they arrive, which need not be the order they were sent; create_modules adds a list in its stated order. The same project_id and name sent again within 5 minutes, to this tool or to create_modules with just that name, returns that module, marked replayed, so a project gets one module per distinct name.

Argument	Type	Default
project_id	string	required
name	string	required

Writes · free

Add several modules to a project

Add several modules to an existing project in one call, numbered in the order given. Free. Returns modules, one entry per created module with its module_id, name, module_number and open_in_frameo link, in the order given. The call returns within about 45 seconds: when Frameo is slow, or refuses a name partway (then error says why), the modules made so far are returned and not_created lists the names still to add, in order; a create_modules with just those names continues the numbering. The same project_id and names sent again within 5 minutes returns the same result, marked replayed, and adds nothing.

Argument	Type	Default
project_id	string	required
names	string[]	required

Writes · free

Create a Frameo project

Create a new Frameo project, with its first module, to generate into. Free. Returns the project_id and the module's module_id that every generate tool takes, and an open_in_frameo link to the new project. The same name and aspect_ratio sent again within 5 minutes returns that project, marked replayed. module_not_created means the project in project_id exists without a module.

Argument	Type	Default
name	string	required
aspect_ratio	string	'9:16'

Writes · free

Make a share link

Make a public Frameo share page for one finished image, video or audio file, for the Share button on a result card. Free. Returns share_url, a content.frameo.ai page that plays the file and links to frameo.ai. A file outside Frameo's production storage has no share page: share_page is false and share_url is the file's own link.

Argument	Type	Default
url	string	required
kind	string	required
share_title	string	optional
share_description	string	optional

Writes · free

Create an upload link

Get a link to upload a file whose bytes the caller sends itself (an HTTP PUT). Free. For clients that can make HTTP requests; show_upload is the card for files on the user's device. The bytes do not pass through this server. The caller sends them: an HTTP PUT to upload_url with the file as the raw body and exactly the headers given in headers, or, for a large file, Azure Put Block and Put Block List calls on upload_url, which send it in parts. upload_url is valid for 60 minutes and for this one file; a fresh call issues another. Once that PUT succeeds, frameo_url is a Frameo link accepted anywhere one is taken -- image_urls, first_frame_url, reference_image_urls, or a lipsync source -- with no further step. Until add_upload_to_library is called with frameo_url, the file is stored against the user's account only and does not appear in any project's Library. Where no HTTP request is possible, the same file can be added in the Frameo app and its link used instead.

Argument	Type	Default
file_name	string	required

Writes · free

Quote the cost of a generation

Quote the Frameo credits a generation will cost. Free. Required before any generate tool. Pass the same settings and project the generate call will use; a changed request needs a new quote. Several generations can be priced at once with items. Returns the credits the generation will cost, and a quote_id the matching generate tool redeems. credits_available is the workspace's balance at the time of the quote (the member's own limit where the workspace sets one), when Frameo reports it. When the quote costs more, short_by is the difference and plans_url links Frameo's plans page; the quote is still issued, and a generate call the balance cannot cover is refused with out_of_credits, uncharged, and its quote is used; a retry takes a new quote. show_credits, given these credits as credits_needed, shows the shortfall on a card that links the plans page and notices when credits arrive. A quote is single-use, valid for 15 minutes, and bound to the settings it priced. The generate tool redeems it alongside confirmed_by_user, which records that the user has seen those credits and agreed to them. settings lists what was priced. A generate call whose settings differ from the quote, or with confirmed_by_user false, is refused uncharged and leaves the quote valid. The same generate call sent again returns the work it started, marked replayed, at no charge; the quote sent with other arguments is refused with quote_used, which names that work. With items, the result has one entry per item in quotes, in order, each with its index and either its own quote_id and credits or its own error. total_credits adds up the items that were quoted, and credits_available, short_by and plans_url compare the balance with that total. Each quote_id is redeemed on its own, so any of the items can be generated and the rest left to expire.

Argument	Type	Default
kind	string	optional
count	integer	1
aspect_ratio	string	'9:16'
project_id	string	optional
module_id	string	optional
duration	number	5
resolution	string	optional
generate_audio	boolean	False
model	string	'seedance_2_5'
text	string	optional
voice_id	string	optional
image_model	string	'nano-banana-pro'
image_resolution	string	optional
reference_count	integer	0
first_frame	boolean	False
items	QuoteItem[]	optional

Writes · free

Extract frames from a video

Pull still images out of a video. Returns Frameo image links. The common use is the LAST frame of a clip, which becomes first_frame_url for generate_video so the next shot continues from exactly where this one ended. Takes up to a minute. Free: no credits are charged. The result also carries small JPEG previews of up to 4 of the frames (at most 384 px) as image content next to the same JSON; previews lists the frame links they show, in the same order as the images.

Argument	Type	Default
video_url	string	required
duration	number	required
at_seconds	number[]	optional
project_id	string	optional
module_id	string	optional

Uses credits

Generate images

Start an image generation in a Frameo project. Uses the user's Frameo credits. Text-to-image, or from image_urls: source images that either EDIT an image or hold a character, product or style steady in a new scene. The prompt says what to keep and what to change ("same woman, now on a beach at sunset"). Supported resolutions and source-image counts vary by model; list_models reports each. Returns generation ids once the work is queued; wait_task returns the images when they are ready. A wait_task timeout leaves the work running and the ids valid. The result is saved in the Frameo project; the finished result's open_in_frameo link opens it there.

Argument	Type	Default
prompt	string	required
aspect_ratio	string	'9:16'
count	integer	1
image_urls	string[]	optional
image_model	string	'nano-banana-pro'
image_resolution	string	optional
project_id	string	optional
module_id	string	optional
request_text	string	optional
shot_number	integer	optional
placement_kind	string	optional
placement_group	string	optional
board_name	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Uses credits

Lip-sync a video to a voiceover

Make the person in a video speak an audio clip (lipsync). Uses the user's Frameo credits. Lipsync is priced per second of video and is among the more expensive tools here. Returns generation ids once the work is queued; wait_task returns the result when it is ready. A wait_task timeout leaves the work running and the ids valid. The result is saved in the Frameo project; the finished result's open_in_frameo link opens it there.

Argument	Type	Default
video_url	string	required
audio_url	string	required
duration	number	required
audio_duration	number	optional
aspect_ratio	string	'9:16'
resolution	string	'480p'
project_id	string	optional
module_id	string	optional
request_text	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Uses credits

Generate a music track

Start a background-music track in a Frameo project. Uses the user's Frameo credits. Returns generation ids once the work is queued; wait_task returns the track when it is ready. A wait_task timeout leaves the work running and the ids valid. The track is saved in the Frameo project.

Argument	Type	Default
prompt	string	required
duration	integer	30
project_id	string	optional
module_id	string	optional
request_text	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Uses credits

Generate a sound effect

Generate a new one-shot sound effect in a Frameo project. Uses the user's Frameo credits. This makes a new sound. search_sound_effects searches a library of ready-made sounds, which are free and instant. Returns generation ids once the work is queued; wait_task returns the sound when it is ready. A wait_task timeout leaves the work running and the ids valid. The sound is saved in the Frameo project.

Argument	Type	Default
prompt	string	required
duration	integer	5
project_id	string	optional
module_id	string	optional
request_text	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Uses credits

Generate a voiceover

Start a voiceover (text to speech) in a Frameo project. Uses the user's Frameo credits. Returns generation ids once the work is queued; wait_task returns the audio and its duration_seconds when it is ready. A wait_task timeout leaves the work running and the ids valid. The voiceover is saved in the Frameo project.

Argument	Type	Default
text	string	required
voice_id	string	required
language_code	string	optional
project_id	string	optional
module_id	string	optional
request_text	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Uses credits

Generate a video

Start a video generation in a Frameo project. Uses the user's Frameo credits. Text-to-video by default. first_frame_url makes the clip open on that image; reference_image_urls instead carry a character, product or look into a new shot. On Seedance models (the default among them) a first frame is run as the lead reference image: the clip opens on it but renders at the requested aspect_ratio, the frame and references can be passed together, and the frame counts as one of the model's reference images. On every other model the clip takes the first frame's own shape, and a call carrying both a frame and references is refused. A request that breaks a model's rules is refused before anything is charged. Returns generation ids once the work is queued. The video takes one to a few minutes, and wait_task returns it when it is ready. On Seedance models, reference images (and a first frame) are prepared before the video starts, and an image's first use can add a short wait. references_registering means that preparation outlasted this call: nothing was charged, the quote is unused, and the same call continues it. reference_image_rejected names an image that was refused, and reference_registration_incomplete one that could not be prepared; nothing was charged for either. The result is saved in the Frameo project; the finished result's open_in_frameo link opens it there.

Argument	Type	Default
prompt	string	required
first_frame_url	string	optional
reference_image_urls	string[]	optional
duration	integer	5
aspect_ratio	string	'9:16'
resolution	string	optional
generate_audio	boolean	False
model	string	'seedance_2_5'
project_id	string	optional
module_id	string	optional
request_text	string	optional
shot_number	integer	optional
placement_kind	string	optional
placement_group	string	optional
board_name	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Read-only · free

Get a skill's instructions

Step-by-step instructions for one Frameo skill, such as a video from a script. Free. Returns the skill text: when it applies, what to ask the user first, the tool calls in order (every paid step is quoted with estimate_cost before it runs), what the user gets, and the names of its reference files, readable with get_skill_file.

Argument	Type	Default
skill_id	string	required

Read-only · free

Get a skill's reference file

One reference file of a skill (a prompt pattern, a shot-list template, a caption style), named in get_skill's `files`. Free.

Argument	Type	Default
skill_id	string	required
file_name	string	required

Writes · free

Check generation status

Report the current state of generations and runs, by their ids. Free. Returns immediately. This is a single snapshot, so a generation still in progress comes back as 'running', with seconds_left, Frameo's estimate of the time it has left, when Frameo gave one. Work Frameo could not be reached to check comes back as 'unchecked', with a hint: it is unaffected, and the same ids can be checked again. wait_task covers the same ids but blocks until they finish. Ids started through any of the user's connections to this workspace are recognised. Ids from several calls, generation ids and run ids alike, can be checked together: the result then has one entry per call in `tasks`, each with its kind ('run' for a run), generation_ids and status, in the order the ids were passed, and the top-level status is 'finished' once every entry is. An id from a multi-result call reports that whole call. A finished video, lipsync, upscale, speech, music or sound effect result has duration_seconds, mapping each media link to its length in seconds, for the links whose length Frameo recorded. For speech it is where the last word ends; the file can run a few tenths of a second longer. A finished image or video result also carries small JPEG previews of up to 4 of its images and videos (at most 384 px; a video by its frame one second in) as image content next to the same JSON; previews lists the links they show, in the same order as the images, and image_urls and video_urls link the full files.

Argument	Type	Default
generation_ids	string[]	required
kind	string	optional

Writes · free

Import media from a link

Copy an image, video or audio file from a public web link into Frameo and a project's Library. Free. Frameo fetches the file from the site itself, so this works where the client cannot send files. Returns frameo_url (accepted anywhere a Frameo link is), kind, bytes, name and open_in_frameo. Each account can import 10 links a minute, and one import takes at most about 50 seconds. A refusal carries error and a hint. Two cases: source_refused means the site serves the file only to a signed-in user or a browser, and the file can be added in the Frameo app, or sent through create_upload_url by a client that can send files; a refusal that still carries frameo_url means the file is stored, or is still being copied there, and add_upload_to_library can file it later.

Argument	Type	Default
url	string	required
project_id	string	optional
module_id	string	optional
name	string	optional

Read-only · free

List a project's characters

List the recurring cast of a Frameo project: each character's name, images and voice. Free. The cast is the project's saved characters: those in its Reference Library (made in the Frameo app, by the app's agent, or with save_character) and those the app's agent keeps for the module. Each character has name, images (up to 6 Frameo image links, which image_urls and reference_image_urls accept), voice_id (a voice generate_speech takes, or null when none is set) and in_library: false for a character the app's agent has only voiced, which has no images until save_character adds it to the Library. At most 30 characters.

Argument	Type	Default
project_id	string	optional
module_id	string	optional

Read-only · free

List a project's Library

List the media in a Frameo project's Library, newest first. Free. The Library holds everything captured for a module, whether or not it was ever placed on the canvas: every generation (from the Frameo app's agent and quick actions, from this server, from ffmpeg runs) and every uploaded or imported file. read_project differs: it reports only what sits on the last saved canvas, by shot. Each item has kind and url (a Frameo link the other tools accept), and where recorded its name, origin, tool, model, prompt (cut to 500 characters) and created_at. counts gives the number of matching items of each kind. At most 60 items are returned per call; when more matched, truncated is true and next_cursor, passed as cursor, returns the next page. Items added after the first page do not shift later pages. open_in_frameo links to the project.

Argument	Type	Default
project_id	string	optional
module_id	string	optional
kind	string	optional
origin	string	optional
cursor	string	optional

Read-only · free

List image and video models

The image or video models Frameo offers, with each one's limits and price. Free. The answer settles which model a named request needs, what a higher-quality option costs, and which rule a refused request broke. For video: the clip lengths, aspect ratios, whether the model starts from an image, how many reference images it accepts, and the price in credits per second at each resolution (silent and with sound). For image: max_source_images, and the price in credits per image at each resolution the model supports (text-to-image, 9:16), plus the shared aspect_ratios. Some image models add credits per source image. The default video model is Seedance 2.5; the default image model is the cheapest sensible choice.

Argument	Type	Default
kind	string	'video'

Read-only · free

List Frameo projects

Find the user's Frameo projects, newest first, optionally by name. Free. A project_id and module_id from here are where the generate tools put results; module_id is optional when the project has a single module. The first five matches list their modules, each with an open_in_frameo link to that module's canvas in the Frameo web app. Later matches carry only project_id and name.

Argument	Type	Default
query	string	optional
limit	integer	10

Read-only · free

List Frameo skills

Step-by-step Frameo skills for videos, UGC ads, photoshoots and more. Free. Two kinds: `workflow` (several tools, minutes to an hour: a script into a video, a UGC review, a product photoshoot) and `recipe` (one generation with a proven prompt pattern: a hero shot, a product spin). kind filters to one of them. Each entry has an id, a one-sentence summary, what the user must bring (`needs`), a rough credit range and time. get_skill returns a skill's full instructions.

Argument	Type	Default
kind	string	optional

Read-only · free

Refresh the credits balance

The Frameo balance card's check. Free. Returns immediately. Chat apps that show Frameo cards hide it from the model; elsewhere it is the same as show_credits, read past Frameo's short balance cache so a purchase shows at once.

Argument	Type	Default
credits_needed	integer	optional

Read-only · free

Refresh the generations gallery

The Frameo gallery card's progress check. Free. Returns immediately. Chat apps that show Frameo cards hide it from the model; elsewhere it is the same as get_task without image previews. Takes the same generation_ids and kind as get_task.

Argument	Type	Default
generation_ids	string[]	required
kind	string	optional

Writes · free

Read a project's canvas

List what is already on a Frameo project's canvas: images, videos and audio, by shot. Free. This is what existing work looks like before something is built on it, as in "animate the second shot" or "add a voiceover to that clip". Every item carries a url: the direct link to its image, video or audio file, which opens or plays in a browser and which the other tools accept as input. The result's open_in_frameo link opens the whole canvas in the Frameo web app. At most 60 items are listed; truncated is true when there are more, and counts covers them all. It reports the last SAVED canvas. The app saves as the user works, so a result produced moments ago is missing until the user has opened the project and it has been placed. recorded_just_now lists up to three of the user's earlier results for this project that had not been added yet (for example from another connection), with their media links; they appear on the canvas the next time the project is opened.

Argument	Type	Default
project_id	string	optional
module_id	string	optional

Writes · free

Render a motion-graphics clip from a template

Render a short motion-graphics clip from one of Frameo's templates: a title card, a lower third, caption lines, an end card, a countdown, or kinetic text. Free. The text is rendered by a browser, so it is exact; Frameo writes the whole page from the template — no HTML is accepted. Returns a run id for wait_task. The clip is recorded in the project's Frameo chat and placed on the canvas: live when the project is open, otherwise the next time it is opened. In one module these runs (ffmpeg, motion graphics, media analysis) go one at a time: while one is in progress, another started in the same module is refused with chat_busy, which is retryable. Other modules are unaffected, and generate tools in the module still run.

Argument	Type	Default
template	string	required
reason	string	required
title	string	optional
subtitle	string	optional
lines	string[]	optional
size	string	'9:16'
duration	number	5
font	string	'Inter'
accent	string	optional
background	string	optional
text_color	string	optional
count_from	integer	optional
count_to	integer	optional
project_id	string	optional
module_id	string	optional

Writes · free

Report a problem to Frameo

Send a report to the Frameo team about Frameo: something that went wrong, works badly or is missing. Free. Problems with these tools are a common case: a tool error, a wrong result, a stuck task or a misleading tool description. A report can come from the user, who asked for it, or from the assistant on its own when it meets a problem; trigger records which. A refusal whose hint explains it, such as an empty wallet, an expired quote or an argument the tool rejected, is Frameo working as intended rather than a problem. The team receives the title, description and type with the account, workspace, assistant app, project and module, and this connection's tool errors from the last hour. Nothing else from the conversation is sent. Returns report_id, which the Frameo team can look the report up by.

Argument	Type	Default
title	string	required
description	string	required
problem_type	string	required
trigger	string	required
project_id	string	optional
module_id	string	optional
tool_name	string	optional

Writes · free

Run an ffmpeg command

Run an ffmpeg command on Frameo media in a project: trim, join, resize, crop or pad, change speed, adjust brightness, contrast or colour (eq), overlay, mix in a voiceover or music, burn captions, extract audio. Free. The command line is the caller's own (argv), run against a private workspace holding the inputs and sidecars; the declared outputs come back as Frameo links. The job runs in a sandbox: no network, workspace files only, a time limit. Returns run_ids at once; wait_task and get_task read the result, which also lands in the project's Frameo chat, and on its canvas once the project is open. An.ass sidecar with the `ass` filter renders text captions more reliably than drawtext. In one module these runs (ffmpeg, motion graphics, media analysis) go one at a time: while one is in progress, another started in the same module is refused with chat_busy, which is retryable. Other modules are unaffected, and generate tools in the module still run. A run takes at most 10 inputs and 4 outputs. Each user has 30 runs per hour across run_ffmpeg, render_motion_graphics and analyze_media.

Argument	Type	Default
inputs	object[]	required
argv	string[]	required
outputs	object[]	required
reason	string	required
sidecars	object[]	optional
project_id	string	optional
module_id	string	optional
request_text	string	optional
timeout_seconds	integer	300

Can overwrite · free

Save a character to a project

Save a character to a Frameo project's cast, so later work reuses its look and voice. Free. The character is added to the project's Reference Library as the Frameo app adds one, and shows in the app's character panel. A name already in the cast is not added again: its voice is set when given, its images are left as they are, and the result says so (saved false).

Argument	Type	Default
name	string	required
image_urls	string[]	required
project_id	string	optional
module_id	string	optional
description	string	optional
voice_id	string	optional

Read-only · free

Search the sound-effect library

Search Frameo's library of ready-made sound effects. Free. A library sound is instant and free, where generate_sound_effect costs credits and takes time. Each result has an `id` to pass as sound_id to add_sound_to_library, and an `audio_url`, the sound file itself, which plays in a browser. An empty result means the library has nothing matching.

Argument	Type	Default
query	string	required
category	string	optional
max_duration	integer	optional
limit	integer	8

Read-only · free

Search voices

Find voices for generate_speech in the user's Frameo voice library. Free. The filters (gender, age, language, accent) are exact matches, so a guessed value returns nothing rather than a near miss. Returns up to `limit` voices (max 20), best first, each with a voice_id for generate_speech and, when Frameo holds a recording of the voice, a sample_url that plays it in a browser. Voices cloned in the workspace are included, marked cloned: true, with yours: true on the user's own clones and false on other members'. The user's own clones rank ahead of other voices when there is no query or the query matches them.

Argument	Type	Default
query	string	''
gender	string	''
age	string	''
language	string	''
accent	string	''
limit	integer	8

Read-only · free

Offer generations to choose from

Show generations as options for the user to pick one, by their ids. Free. Returns immediately. In chat apps that display Frameo cards, the card shows each generation as in show_generations, with question as its heading and a "Use this" button on every finished one. Pressing it posts the user's pick into the conversation as their own message, naming the chosen link. The card uses no credits. Where cards are not displayed, only the result below comes back. The result is get_task's snapshot of those ids, without image previews.

Argument	Type	Default
generation_ids	string[]	required
question	string	optional
kind	string	optional

Read-only · free

Show credits

Show the workspace's Frameo credits against what a request costs, with a link to the plans page, on a card. Free. In chat apps that display Frameo cards, the card shows the balance against credits_needed and a Plans and credits button that opens Frameo's plans page signed in as this connection's user. Once that button is pressed, the card rechecks the balance every few seconds for up to 15 minutes, and when the balance covers credits_needed a Continue button posts "I added Frameo credits" into the chat. The card uses no credits. Where cards are not displayed, only the result below comes back. Returns credits (the workspace's balance, the member's own limit where the workspace sets one, or null when Frameo does not report it), has_active_plan (true for a subscription or a live trial; without either, Frameo refuses to charge whatever the balance), credits_needed, short_by when both are known, and plans_url, which links Frameo's plans page; it is information, and nothing is bought through it.

Argument	Type	Default
credits_needed	integer	optional

Read-only · free

Show generations

Show generations to the user as an interactive card in the chat, where the chat app supports MCP Apps, by their ids. Free. Returns immediately. A generation takes seconds to a few minutes, and a whole job tens of minutes. The card is shown as soon as the work starts: the user watches each generation's progress live and every result as it lands. It is for the user only; wait_task is how the assistant gets updates and results. Called before wait_task, the card shows progress while wait_task waits. A card covers one wave of work: every generation or run started before the next wait_task, shown once with all their ids before that wait. The same ids appear again only as the finished result (final true). A single quick call needs no card. One card covers the generations running at the same time, up to 24 ids from any generate or run calls, in one call. A single id makes a complete card when it is the only generation running. Each call adds a new card, so generations running together but shown one call at a time stack separate cards in the chat. Without MCP Apps support, only the result below comes back. The result is get_task's snapshot of those ids, without image previews. With final, the card offers Download and Share on each finished item.

Argument	Type	Default
generation_ids	string[]	required
kind	string	optional
final	boolean	False
share_title	string	optional
share_description	string	optional

Read-only · free

Upload files to Frameo

Open a card where the user picks files from their device to upload to Frameo. Free. In chat apps that display Frameo cards, the card sends each picked file straight to Frameo storage through create_upload_url, files it in the project's Library through add_upload_to_library when a project is given, and then posts the files' frameo_url links into the conversation as a message from the user. Those links are accepted anywhere a Frameo link is taken. Where cards are not displayed, nothing is uploaded and only the result below comes back. Returns accepts, the file extensions taken with each one's kind and size limit in MB, and the project_id and module_id the files go to, if any.

Argument	Type	Default
project_id	string	optional
module_id	string	optional

Writes · free

Switch the Frameo workspace

Move this connection to another workspace the user belongs to, by its id from whoami's workspaces. Free. From the next call on, every tool works in that workspace: its projects, Library, voices and characters, and its credits are the ones spent. Quotes from estimate_cost that were not yet redeemed are discarded, since they priced work against the previous workspace. Runs started before the switch belong to the workspace that started them: get_task and wait_task report run_not_found for them, and their results are recorded in that project's chat only once the connection is switched back, within 7 days of the run starting. Returns the workspace now active and its credits.

Argument	Type	Default
workspace_id	string	required

Uses credits

Upscale a video

Make a video sharper and higher resolution. Uses the user's Frameo credits. Upscaling is priced per second of video, and is normally the last step, applied to finished clips. Returns generation ids once the work is queued; wait_task returns the result when it is ready. A wait_task timeout leaves the work running and the ids valid. The result is saved in the Frameo project; the finished result's open_in_frameo link opens it there.

Argument	Type	Default
video_url	string	required
duration	number	required
factor	number	2.0
aspect_ratio	string	'9:16'
resolution	string	'480p'
project_id	string	optional
module_id	string	optional
request_text	string	optional
quote_id	string	optional
confirmed_by_user	boolean	False

Writes · free

Wait for generations to finish

Wait for generations and runs to finish, then return the result. Free. Blocks for up to timeout_seconds (max 50), polling internally, and returns the same shape as get_task. Work longer than that window returns with status 'running': it is unaffected, and the same ids can be waited on again until it reports 'finished'. In chat apps that show cards, the user sees this work only on a show_generations card: without one on these ids, they see nothing while it runs, and a whole job (a batch of clips, a cut) takes tens of minutes across many wait_task calls.

Argument	Type	Default
generation_ids	string[]	required
timeout_seconds	integer	50
kind	string	optional

Read-only · free

Check the Frameo connection

Confirm the Frameo connection: who is signed in, which workspace is active, and its credits. Free. workspaces lists every workspace the user belongs to; switch_workspace moves the connection to another of them. credits is the active workspace's balance (the member's own limit where the workspace sets one), or null when Frameo does not report it. spent_by_this_connection is what this connection has spent. plans_url links Frameo's plans page, which describes the plans and credits; it is information, and nothing is bought through it.

No arguments.