Frameo MCP server reference
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:
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)
- add_sound_to_library
- add_upload_to_library
- analyze_media
- create_handoff
- create_module
- create_modules
- create_project
- create_share_link
- create_upload_url
- estimate_cost
- extract_frames
- generate_image
- generate_lipsync
- generate_music
- generate_sound_effect
- generate_speech
- generate_video
- get_skill
- get_skill_file
- get_task
- import_media_url
- list_characters
- list_library
- list_models
- list_projects
- list_skills
- poll_credits
- poll_generation
- read_project
- render_motion_graphics
- report_problem
- run_ffmpeg
- save_character
- search_sound_effects
- search_voices
- show_choices
- show_credits
- show_generations
- show_upload
- switch_workspace
- upscale_video
- wait_task
- whoami
add_sound_to_library 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 |
add_upload_to_library 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 |
analyze_media 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 |
create_handoff 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 |
create_module 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 |
create_modules 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 |
create_project 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' |
create_upload_url 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 |
estimate_cost 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 |
extract_frames 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 |
generate_image 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 |
generate_lipsync 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 |
generate_music 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 |
generate_sound_effect 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 |
generate_speech 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 |
generate_video 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 |
get_skill 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 |
get_skill_file 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 |
get_task 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 |
import_media_url 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 |
list_characters 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 |
list_library 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 |
list_models 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' |
list_projects 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 |
list_skills 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 |
poll_credits 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 |
poll_generation 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_project 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 |
render_motion_graphics 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 |
report_problem 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 |
run_ffmpeg 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 |
save_character 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 |
search_sound_effects 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 |
search_voices 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 |
show_choices 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 |
show_credits 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 |
show_generations 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 |
show_upload 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 |
switch_workspace 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 |
upscale_video 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 |
wait_task 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 |
whoami 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.