Frameo

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

Frameo is an AI video production platform that takes an idea or a script to a finished short film, micro-drama, ad or social video. Images, video clips, voiceovers, music and sound effects are generated with the latest models, such as Seedance, Kling and Veo, kept consistent from shot to shot, and edited and assembled on one canvas. This MCP server brings that to Claude, ChatGPT, Cursor and any other MCP client, working in the user's own Frameo account.

The reference below 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 and Library. This connection works in one workspace at a time. What this connection makes is recorded in the module's 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. Before writing an image or video prompt from scratch, list_presets and get_presets have tested prompts for camera moves, lighting, framing, product shots and effects. 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; the card updates itself, so the same ids are not shown again. wait_task collects the results. Choosing the tool: - Files on the user's device: show_upload. A web link: import_media_url. Files attached in the chat, where the app passes them (ChatGPT): import_attachments. - 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 and view_image shows one image or video frame in detail, 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 (58)

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. Finishes at once and returns the sound's name, its audio_url and open_in_frameo, the project's link in Frameo.

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 module in Frameo. 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. The finished result's analysis is markdown. For a video: an overall summary, an audio summary, a timestamped transcript when there is speech, then the scenes; with detect_shots each scene is one shot, headed `Shot N` with its `(start_ms=N, end_ms=N)`, which go verbatim into extract_frames to grab that shot's frames and clip. For audio: an overall summary, the audio analysis and a transcript of `speaker: text` lines, each with its measured start and end, safe to cut at. 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 module_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
detect_shots	boolean	True
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 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; a name the project already has returns that module, marked existing, 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. A name the project already has is not added again: its entry is that module, marked existing. 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, separate Frameo project, with its first module, to generate into. Free. Each call makes another project. Work already under way keeps the project_id it has, even when its plan, title or shape changes: rename_project renames a project, and each generation carries its own aspect_ratio. list_projects finds the user's earlier projects by name. 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 or video, for the Share button on a result card. Free. Returns share_url, a frameo.ai page that plays the file, shows the title, the prompt, the sharer's first name, the model, the size and the input images, and links to Frameo. Audio, a file outside Frameo's storage, and a call without generation_id have no share page: share_page is false and share_url is the file's own link. A generation id this user did not start in this workspace in the last 7 days returns unknown_generations.

Argument	Type	Default
url	string	required
kind	string	required
generation_id	string	optional
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

Can overwrite · free

Delete a module

Delete a project's last module, with its canvas and Library. Free; cannot be undone. Frameo deletes only the module with the highest module_number; any other is refused with not_last_module, which names the last one. Without confirmed_by_user it deletes nothing and answers not_confirmed with the module's name and project_name, for the user to agree to by name; the same call with confirmed_by_user true then deletes it, and no tool restores it. Frameo allows it to the project's owner and managers; another role is refused with not_permitted. Returns the project_id, module_id and the name it had, with deleted true and modules_left. The same call sent again within 5 minutes returns that result, marked replayed.

Argument	Type	Default
project_id	string	required
module_id	string	required
confirmed_by_user	boolean	False

Can overwrite · free

Delete a project

Delete a Frameo project with all its modules, canvases and Library. Free; cannot be undone. Without confirmed_by_user it deletes nothing and answers not_confirmed with the project's name and module_count, for the user to agree to by name; the same call with confirmed_by_user true then deletes it. The project leaves list_projects and the Frameo app, and no tool restores it. Frameo allows it only to the project's owner; another role is refused with not_permitted. Returns the project_id and the name it had, with deleted true. The same call sent again within 5 minutes returns that result, marked replayed.

Argument	Type	Default
project_id	string	required
confirmed_by_user	boolean	False

Writes · free

Quote the cost of a generation

Quote the Frameo credits a generation will cost. Free. Required before any generate tool. Returns the credits the generation will cost, a quote_id the matching generate tool redeems, and settings, what was priced. A quote is single-use, valid for 15 minutes, and bound to the settings and project it priced. The generate tool redeems it alongside confirmed_by_user, which records that the user has seen those credits and agreed to them. 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. Never take a new quote to recover a call whose outcome is unclear. Several generations can be priced at once with items. 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 account_url links where credits are managed; 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. 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 account_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
prompt	string	optional
voice_id	string	optional
image_model	string	'nano-banana-pro'
image_resolution	string	optional
reference_count	integer	0
first_frame	boolean	False
middle_frame	boolean	False
last_frame	boolean	False
reference_video_url	string	optional
items	QuoteItem[]	optional

Writes · free

Extract frames from a video

Pull still images out of a video, and optionally cut a range of it into a clip. Returns Frameo links. Free: no credits are charged. 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. With start_ms and end_ms (for example one shot's bounds, copied verbatim from an analyze_media run with detect_shots), the range is also cut into its own clip, returned as clip.url (a link only: it is not added to the module's Library or canvas), and every moment in at_seconds lies inside the range. One call covers one range; several shots take one call each, and they can run in parallel. Answers within about 50 seconds. 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	optional
at_seconds	number[]	optional
start_ms	integer	optional
end_ms	integer	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. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. 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. Where the chat app shows cards, show_generations with these ids shows the work to the user; wait_task returns it to the assistant. 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. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. For a person on screen who has to say exact words in a chosen voice, generate_speech makes the voiceover and this matches the mouth to it. Lipsync is priced per second of video and is among the more expensive tools here. The result runs as long as the voiceover. Returns generation ids once the work is queued; wait_task returns the result when it is ready. Where the chat app shows cards, show_generations with these ids shows the work to the user; wait_task returns it to the assistant. 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. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. Returns generation ids once the work is queued; wait_task returns the track when it is ready. Where the chat app shows cards, show_generations with these ids shows the work to the user; wait_task returns it to the assistant. 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. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. 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. Where the chat app shows cards, show_generations with these ids shows the work to the user; wait_task returns it to the assistant. 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. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. Returns generation ids once the work is queued; wait_task returns the audio and its duration_seconds when it is ready. Where the chat app shows cards, show_generations with these ids shows the work to the user; wait_task returns it to the assistant. A wait_task timeout leaves the work running and the ids valid. The voiceover is saved in the Frameo project. When a person on screen has to say this exact audio, generate_lipsync then makes their mouth match it.

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. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. Text-to-video by default. first_frame_url opens the clip on that image, and middle_frame_url and last_frame_url pass through and end on theirs; reference_image_urls instead carry a character, product or look into a new shot, and reference_audio_urls guide its sound; reference_video_url continues or edits an existing clip. On Seedance models (the default among them) frames guide the clip rather than pin it: it opens on the first and moves toward the last, renders at the requested aspect_ratio, combines frames, reference images and reference audio, and counts each frame as one reference image. On every other model the clip takes the first frame's own shape, and frames with reference images or audio are 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. Where the chat app shows cards, show_generations with these ids shows the work to the user. On Seedance, reference images and frames are prepared before the video starts, and an image's first use can add a short wait. references_registering means that 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; its open_in_frameo link opens it there.

Argument	Type	Default
prompt	string	required
first_frame_url	string	optional
middle_frame_url	string	optional
last_frame_url	string	optional
reference_image_urls	string[]	optional
reference_audio_urls	string[]	optional
reference_video_url	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 Frameo presets

The prompt text of up to 10 presets, for an image or video prompt. Free. Each preset has its prompt (used as written, then tied to the scene), when to use it, notes, and any reference images, videos or audio to pass along with it. Ids that are not found are listed in missing; when none is found, the call returns unknown_preset.

Argument	Type	Default
preset_ids	string[]	required

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) and what the user gets. `files` lists the skill's own files, readable with get_skill_file; `uses` lists the other skills, their files, and the presets and preset categories the text calls. Load each when its step comes.

Argument	Type	Default
skill_id	string	required

Read-only · free

Get a skill's file

Read one file of a Frameo skill, such as a shot-list template or a caption style. Free. A skill's text names a file at the step that needs it, as get_skill_file(skill_id=..., path=...): call it then, with exactly that skill_id and path. A text can point at another skill's file; that skill does not need loading first. Returns the file's text and `uses`: the other skills, their files, and the presets and preset categories this file calls.

Argument	Type	Default
skill_id	string	required
path	string	required

Read-only · free

Check generation status

Report the current state of generations and runs, by their ids. Free. Returns immediately. A single snapshot: work still in progress comes back as 'running', with seconds_left, Frameo's estimate of the time it has left, when Frameo gave one; wait_task takes the same ids and blocks until they finish. 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. Each failed generation in failed, and a failed run, carries reason: one short sentence on why it failed and what usually works instead. A finished generation reports credits_charged (with credits_quoted and charge_note when the charge differed from the quote) and saved_to_project: true with open_in_frameo, its link in the project. Where saved_to_project is false, save_hint says why; the file links still work. Ids the user started in this workspace in the last 7 days, through any of their connections, 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 files attached in the chat

Import images, videos or audio the user attached in the chat into Frameo and a project's Library. Free. In chat apps that pass attached files to apps (ChatGPT), the app fills files with the user's attachments itself. Where attachments do not arrive here, show_upload takes files from the user's device and import_media_url takes a web link. Takes PNG, JPEG or WebP (up to 20 MB), MP4 or MOV (up to 200 MB), MP3, WAV or M4A (up to 50 MB). The files are imported together, and each one is named after its file name in the Library. Returns files, one entry per file in the order given: index, and frameo_url (accepted anywhere a Frameo link is), kind, bytes and name, or that file's own error and hint. Also open_in_frameo. Each account can import 10 files a minute, links included, and one call takes at most about 50 seconds. A refused file that still carries frameo_url is stored, or is still being copied there, and add_upload_to_library can file it later.

Argument	Type	Default
files	AttachedFile[]	required
project_id	string	optional
module_id	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 saying what to do next. source_refused means the site serves the file only to a signed-in user or a browser, or the link has expired, so the same link fails again: show_upload takes the file from the user's device, import_attachments takes it attached in the chat (ChatGPT), and the Frameo app takes any file. 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 or with save_character) and those the app 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 kept only in the module's notes under /characters (by the app or save_note), 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. Each image, video and audio item has a media_id, which show_generations and show_choices take to show it on a card. 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 this Frameo workspace 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, whether it takes a source clip to continue or edit (from_video), which frames it takes (first, middle, last), how many reference images and reference audio clips it accepts, and the price in credits per second at each resolution (silent and with sound). For image: aspect_ratios, max_source_images, and the price in credits per image at each resolution the model supports (text-to-image, 9:16). Some image models add credits per source image. default names the video model to use when none is asked for: Seedance 2.5, or where the workspace does not offer it, the next one Frameo prefers. The default image model is a tested, general-purpose choice.

Argument	Type	Default
kind	string	'video'

Read-only · free

List a module's notes

List the notes a module keeps (scenes, beats, cast, assets) under a path. Free. Each module keeps a JSON tree of notes addressed by unix-style paths, such as /scenes/1/beat or /characters/lucy/voice_id. The Frameo app reads and writes the same tree, so notes kept on either side are visible to the other. Returns entries [{name, kind ("dir" or "leaf"), bytes, updated_at (top-level keys only)}], at most 200, with truncated and total when there are more. Paths start with "/" and have no empty, "." or ".." segments.

Argument	Type	Default
path	string	'/'
scope	string	optional
project_id	string	optional
module_id	string	optional

Read-only · free

List Frameo presets

Find presets: short, tested prompts for camera moves, lighting, framing, product shots, effects and more, to use in an image or video prompt. Free. Before writing an image or video prompt from scratch, look here: there is often a tested preset for the shot, the camera move, the light or the effect, and it gives steadier results than an improvised prompt. Most presets are a piece of a prompt; some categories hold a whole image, a whole clip, a caption style or a line delivery, and each preset's when and notes say where it goes. Called with no arguments, it returns the categories, each with its sub-categories and counts. With query it searches, best match first, leaving out presets that match only a small part of the query; with category or sub_category it browses. Either way at most 30 presets come back, with total, the number that matched. Each entry has preset_id, title, category, sub_category, description and when to use it; get_presets returns the prompt text. A search with no match returns no presets and the categories: the library has nothing for that need. A camera move, a framing or a lighting look adds to another prompt; a product shot or an ad layout is a whole image on its own; an effect is a whole clip made from one still.

Argument	Type	Default
category	string	optional
query	string	optional
sub_category	string	optional

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 up to 20 modules each, with module_count and an open_in_frameo link to each module's canvas in the Frameo web app; modules_truncated is true when a project has more, and list_projects with that project_id lists them all. Later matches carry only project_id and name.

Argument	Type	Default
query	string	optional
limit	integer	10
project_id	string	optional

Read-only · free

List Frameo skills

Step-by-step Frameo skills for almost any job: films, UGC ads, photoshoots and edits. Free. There is a skill for most requests: script-to-video turns a script into a film with a consistent cast and spoken dialogue, faceless-story-video makes a narrated explainer, story or kids' song, ugc-video makes creator-style product ads, product-photoshoot makes store and ad stills, thumbnail-set makes thumbnails and covers, review-shots checks a set of shots and the finished cut, and others cover presenters, character sheets, ad remakes and re-cutting footage the user already has. Check this list before planning a multi-step job yourself: a skill sets the models, prompts, checks and order that work. Each entry has a skill_id, a title, a one-sentence summary of what it makes, when to use it, and a version. get_skill returns a skill's full instructions.

No arguments.

Read-only · free

Frameo

The Frameo home, opened by the user from ChatGPT's sidebar or a conversation tab: the workspace and its credits, the newest projects with their latest images and videos, and the kinds of work Frameo has a skill for. Free. Hidden from the model. The user writes what to make on the home, picks a project or a starting point, and the home posts it into the chat as the user's message; it spends nothing and starts no work. Returns workspace_name, credits (null when Frameo does not report them), app_url (the Frameo web app) and projects: the newest few, each with project_id, name, module_count, its first module with an open_in_frameo link, and recent, that module's latest images and videos with kind, url, still, prompt and created_at. list_skills and list_models list the skills and models the card offers.

No arguments.

Read-only · free

Refresh the balance

The balance widget's check. Free. Returns immediately. Chat apps that show widgets hide it from the model; elsewhere it is the same as show_balance, but read fresh, so a change in the balance shows at once.

Argument	Type	Default
generation_quote	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

Read-only · free

Refresh the Frameo home

The Frameo home card's refresh of the newest projects. Free. Returns immediately. Chat apps that show Frameo cards hide it from the model; elsewhere it returns projects as open_frameo does: the newest first, each with project_id, name, module_count, its first module with an open_in_frameo link, and recent, that module's latest images and videos (for the newest six only; later projects carry an empty recent).

Argument	Type	Default
limit	integer	6

Read-only · free

Read a module's note

Read the note at one path of a module's notes, such as a scene, beat or cast entry. Free. Each module keeps a JSON tree of notes addressed by unix-style paths, such as /scenes/1/beat or /characters/lucy/voice_id, shared with the Frameo app. Returns value, the JSON at path. A value over 50 KB is refused with value_too_large, except a string, which comes back cut to 50 KB with truncated: true. A string like "$state:/assets/<id>/url" points to another path in these notes: read that path for the value. Other tools take the value itself (such as a Frameo link), not the pointer. Paths start with "/" and have no empty, "." or ".." segments.

Argument	Type	Default
path	string	required
scope	string	optional
project_id	string	optional
module_id	string	optional

Read-only · 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, and a media_id, which show_generations and show_choices take to show it on a card. 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 are not on the saved canvas yet (for example from another connection), with their media links; they appear there the next time the project is opened.

Argument	Type	Default
project_id	string	optional
module_id	string	optional

Can overwrite · free

Rename a module

Rename a module in a Frameo project. Free. Only the name changes: the module's canvas, Library, notes and module_number stay as they are. Returns the project_id, module_id, the new name and previous_name.

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

Can overwrite · free

Rename a project

Rename a Frameo project. Free. Only the name changes: the project's modules, canvases, Library and settings stay as they are. Frameo allows it to the project's owner and managers; another role is refused with not_permitted. Returns the project_id, the new name and previous_name.

Argument	Type	Default
project_id	string	required
name	string	required

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 module in Frameo 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 module_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 is also recorded in the module, and placed 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 module_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

Can overwrite · free

Save a module's note

Save a top-level note in a module (scenes, cast, a shot list). Free. Each module keeps a JSON tree of notes, shared with the Frameo app (list_notes and read_note read it). Only the module's own notes are written; the project-level notes and other modules are read-only. Each entry under /characters is also listed by list_characters as a character of the project, named by its name field or its key, with no images until save_character adds it. A key that exists is refused with top_level_key_exists, except an object onto an object, which merges; overwrite_existing replaces the whole value. /assets holds Frameo's own records and cannot be saved over. The result has path, bytes (the size of the top-level value afterwards) and created (true when a new top-level key was made, which can mean a mistyped path); corrections lists any input Frameo repaired, such as a list stored as keyed objects. Writes in one module apply one at a time; while an ffmpeg, motion-graphics or media-analysis run is in progress there, a save is refused with module_busy, which is retryable. A save not finished within about 20 seconds returns status running with run_ids, and wait_task reads its result.

Argument	Type	Default
path	string	required
value	any	required
project_id	string	optional
module_id	string	optional
overwrite_existing	boolean	False
request_text	string	optional

Read-only · free

Search a module's notes

Find text in a module's notes and return the paths whose values contain it. Free. Each module keeps a JSON tree of notes addressed by unix-style paths, such as /scenes/1/beat or /characters/lucy/voice_id, shared with the Frameo app. Returns matches [{path, snippet}] for the string values under path that contain text, at most 50, at most 6 levels deep. Paths start with "/" and have no empty, "." or ".." segments.

Argument	Type	Default
text	string	required
path	string	'/'
scope	string	optional
project_id	string	optional
module_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

Show balance

Show the workspace's balance, against what a request costs. Free. In chat apps that show widgets, the widget shows the balance and, given generation_quote, whether it covers that amount, with a Manage credits button that opens frameo.ai signed in as this connection's user. After that button is used, the widget rechecks the balance every few seconds for up to 15 minutes, and once the balance covers generation_quote a Continue button lets the user carry on in the chat. The widget uses no credits. Where widgets are not shown, only the result below comes back. Returns the balance and, given generation_quote, short_by. Nothing is bought through this tool.

Argument	Type	Default
generation_quote	integer	optional

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 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 card updates itself as the work finishes and offers Download and Share on each finished item, so the same ids are not shown again. Every result the user should see goes on a card. One card covers the generations running at the same time. 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. Work already in a project, made in the Frameo app, by a teammate or earlier, is shown by the media_id list_library or read_project gives each item, as finished. The result is get_task's snapshot of those ids, without image previews.

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. Files the user already attached in the chat go through import_attachments in apps that pass attachments to apps, such as ChatGPT. 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 saved to that project 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

Can overwrite · free

Update a module's notes

Change part of a module's notes: merge a value in at any path, or remove a key. Free. Each module keeps a JSON tree of notes, shared with the Frameo app (list_notes and read_note read it). Only the module's own notes are written; the project-level notes and other modules are read-only. The value merges at path: objects merge, a value replaces a non-object, null removes a key, and missing parent objects are created; on "/" with {"<key>": null} it removes a top-level key. /assets records belong to Frameo: only annotations on existing records can be patched. The result has path, bytes (the size of the top-level value afterwards) and created (true when a new top-level key was made, which can mean a mistyped path); corrections lists any input Frameo repaired, such as a list stored as keyed objects. Writes in one module apply one at a time; while an ffmpeg, motion-graphics or media-analysis run is in progress there, an update is refused with module_busy, which is retryable. An update not finished within about 20 seconds returns status running with run_ids, and wait_task reads its result.

Argument	Type	Default
path	string	required
value	any	required
project_id	string	optional
module_id	string	optional
request_text	string	optional

Uses credits

Upscale a video

Make a video sharper and higher resolution. Uses the user's Frameo credits. Paid: pass the quote_id estimate_cost returned for these settings (single-use, valid 15 minutes) and confirmed_by_user once the user has agreed to its credits; without them, or with other settings, the call is refused uncharged. When a call's outcome is unclear, send the same call again with the same quote_id: it returns the work already started, marked replayed, and charges nothing. Never take a new quote to recover a call; a new quote starts new work. 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. Where the chat app shows cards, show_generations with these ids shows the work to the user; wait_task returns it to the assistant. 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

Read-only · free

View an image or video frame

Look at an image, or one frame of a video, in enough detail to check it: read small text, count fingers, compare a face with its reference, spot artifacts. Free; nothing is generated, saved or charged. Takes a link a Frameo tool returned (generations, read_project, list_library, extract_frames, uploads, imports); any other link returns url_not_from_frameo, and import_media_url brings an outside file into Frameo first. A video link (.mp4,.mov,.webm) shows the single frame at at_seconds. Returns the picture as JPEG image content, scaled down to fit resolution (never enlarged), next to a short JSON block: url, kind (image or video_frame), max_edge (the resolution's limit, not the picture's own size), and at_seconds for a video. Other tools' results carry previews of at most 384 px; this is the larger view. image_unavailable means Frameo could not produce the picture: the file does not exist or is not an image or video, or at_seconds is past the video's end.

Argument	Type	Default
url	string	required
resolution	'default' | 'high' | 'max'	'default'
at_seconds	number	1.0

Read-only · 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) 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: one card per wave, with every id started since the last wait_task, shown before waiting on them. Without one, 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. A finished image or video result carries small previews of its images and videos, and view_image shows one in full detail, so a result can be checked against the request before it is built on. A finished generation also reports credits_charged and saved_to_project.

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. account_url links frameo.ai, where the account's credits are managed; nothing is bought through this tool.

No arguments.