Frameo

Start a voiceover (text to speech) in a Frameo project. Spends the user's Frameo credits. voice_id: from search_voices. text: the words to speak, at most 2500 characters. language_code: only for voices whose engine is "gemini": the language's name as Gemini lists it, e.g. "Hindi (India)" or "English (US)"; omitted, Gemini detects it from the text. Other voices speak the text's own language and ignore it; the result's note says so. quote_id comes from estimate_cost(kind="speech") for the same text, voice and project; speech is priced by the length of the text. confirmed_by_user records that the user agreed to the quoted credits. request_text: what the user asked for, in their words. It is shown in the project's Frameo chat. 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 lands in the project's Frameo chat, and on its canvas once the project is open. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

generate_speech

Start an image generation in a Frameo project. Spends the user's Frameo credits. image_urls: optional source images, all links returned by Frameo tools (generated or uploaded). They either EDIT an image or hold a character, product or style steady in a new scene. The FIRST is the base image and the rest are references; how many a model accepts in total is its max_source_images in list_models, and it varies by model. The prompt says what to keep and what to change ("same woman, now on a beach at sunset"). Omitted, the call is plain text-to-image. image_model / image_resolution: see list_models, which also reports the resolutions each model supports. The defaults are the cheapest sensible choice; resolution omitted is 2K, or the model's highest tier below 2K when it has none. quote_id comes from estimate_cost for the same count, aspect_ratio, image_model, image_resolution, project and number of image_urls (estimate_cost's reference_count). confirmed_by_user records that the user agreed to the quoted credits. request_text: what the user asked for, in their words. It is shown in the project's Frameo chat. aspect_ratio: one of 1:1, 16:9, 9:16, 3:4. count: one image per call; call again for more variants. project_id / module_id: the project and module the image is saved in, from list_projects. project_id is required; module_id is optional when the project has a single module. 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. shot_number: the story shot this belongs to, counting from 1 in the sequence; reuse it for retakes. Each shot gets its own row on the canvas, in order, and a shot's image and its video share that row. placement_kind: "character", "prop" or "location" for reference work (a character sheet, a prop, a location plate), when introducing it and when regenerating it; omitted for story shots. References land on their own board, apart from the shots that use them. For a video, a shot_number takes precedence; for an image, placement_kind does. placement_group: required with placement_kind (and only with it): the reference subject's name (e.g. "nova"), the same on every call for that subject, so its images share one row. board_name: a name for a NEW reference board of that kind (e.g. "Lumio props"), on its first generation only; ignored when the board exists.

generate_image

The full instructions of one skill from list_skills. 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.

get_skill

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

get_skill_file

Copy an image, video or audio file from a public web link into Frameo and a project's Library. Free. url: an https link to the file itself: PNG, JPEG or WebP (up to 20 MB), MP4 or MOV (up to 200 MB), MP3, WAV or M4A (up to 50 MB). Frameo fetches it from the site itself, so this works where the client cannot send files. Links behind a sign-in, and links on private networks, are refused. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module. name: the Library tile's name. Defaults to the file name in the link. 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.

import_media_url

Make the person in a video speak an audio clip (lipsync). Spends the user's Frameo credits. video_url: a video made with generate_video, with ONE clearly visible speaker. audio_url: a voiceover made with generate_speech. audio_duration: the voiceover's length in seconds, if known. When it is longer than the video, the video plays back and forth so the speech is not cut off. duration: the video's length in seconds, as exact as known (e.g. 5.04); it is priced in whole seconds, rounded up. aspect_ratio and resolution: the same values the video was generated with. quote_id comes from estimate_cost(kind="lipsync") for the same duration and project. confirmed_by_user records that the user agreed to the quoted credits. Lipsync is priced per second of video and is among the more expensive tools here. request_text: what the user asked for, in their words. It is shown in the project's Frameo chat. 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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

generate_lipsync

Find the user's Frameo projects, newest first. Pass query to search by name. 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.

list_projects

The things Frameo can make end to end, as step-by-step skills. 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.

list_skills

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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module. kind: image, video, audio or doc, to list only that kind. origin: to list only items with that origin, such as generated, upload, quick_action, extracted, ffmpeg_job or attached. cursor: the next_cursor of an earlier call, for the page that follows it. 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.

list_library

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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

list_characters

The image or video models Frameo offers, with each one's limits and price. Free. kind: "video" or "image". 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 models are the cheapest sensible choice.

list_models

Make a public Frameo share page for one finished image, video or audio file, for the Share button on a result card. Free. url: the file's link from a finished generation. kind: image, video or audio. share_title / share_description: shown on the page and in link previews, up to 100 and 250 characters. Returns share_url, a content.frameo.ai page that plays the file and links to frameo.ai. A file outside Frameo's production storage has no share page: share_page is false and share_url is the file's own link.

create_share_link

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 spends nothing. Where cards are not displayed, only the result below comes back. generation_ids: 2 to 12 generation ids, shown in the order given. question: the choice put to the user, such as "Which cover should become the video?". kind is as in get_task. The result is get_task's snapshot of those ids, without image previews.

show_choices

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. destination: a link on the Frameo web app, such as a result's open_in_frameo link. 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.

create_handoff

Quote the Frameo credits a generation will cost. Free. Required before any generate tool. reference_count: the number of source images the generate call will pass -- image_urls for kind="image" (0 for text-to-image), reference_image_urls for kind="video". Some models charge per source or reference image, so the quote is bound to that count. first_frame: for kind="video", whether the generate call will pass a first_frame_url. It does not change the price; it lets the quote refuse up front what the generate call would (on Seedance the frame is one more reference image, so with a frame the most is one fewer). count: images per call, which is 1. kind: "image", "video", "lipsync", "upscale", "speech", "music" or "sound_effect". Pass the same settings and project you will generate with; a changed request needs a new quote. resolution, generate_audio and model apply to video only; resolution omitted is the model's lowest tier. duration (seconds) applies to video, lipsync, upscale, music and sound_effect. For lipsync it is the length of the source video, which is what it is priced by. text applies to speech, music and sound_effect: the words to speak, or the music / sound prompt. All three are priced by the length of that text, so the generate call's text has to cost the same. voice_id applies to speech only. 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. 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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module. items: several generations priced in one call, up to 10, in place of kind and the settings above. Each item takes those same settings, priced exactly as a single call prices them; an item without project_id uses the project_id and module_id given alongside 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.

estimate_cost

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. Before reading, this user's earlier generations and library sounds for the project that were not added to its Frameo chat (for example ones started through another connection, or saved while an ffmpeg, motion-graphics or media-analysis run was in progress) are added; recorded_just_now lists up to three of them with their media links, and they are placed on the canvas the next time the project is opened. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

read_project

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.

poll_generation

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. template: title_card | lower_third | caption_card | end_card | countdown | kinetic_text. title / subtitle: the text for title_card, end_card and lower_third (name / role). lines: the lines for caption_card and kinetic_text, up to 12 of 80 characters each, shown one after another across the duration. count_from / count_to: the countdown's numbers, one per second, at most 30 numbers (the duration follows from them; `duration` is ignored). size: 9:16 (1080x1920), 16:9 or 1:1. duration: 1 to 30 seconds. font: one of the baked-in fonts (Inter, Poppins, Montserrat, Oswald, Jost, Archivo, Space Grotesk, Playfair Display, Bebas Neue, Anton, Red Hat Display, Darker Grotesque). accent / background / text_color: six-digit hex colours like #1A1A1A; background may be "transparent" (lower_third and caption_card default to it and come back as an alpha webm for compositing with run_ffmpeg; the rest are mp4). reason: one line shown in the project's Frameo chat. 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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

render_motion_graphics

Run an ffmpeg command on Frameo media in a project: trim, join, overlay, mix in a voiceover or music, burn captions, extract audio, change speed, resize. Free. The command line is the caller's own, run against a private workspace: - inputs: [{"name": "a.mp4", "url": <Frameo link>}, ...]. Each becomes a file in the workspace named exactly `name`. Links are Frameo links (from other tools). - argv: the arguments after `ffmpeg`, e.g. ["-i","a.mp4","-i","voice.mp3","-map","0:v", "-map","1:a","-shortest","out.mp4"]. Files are named by their workspace names only: a path, `/`, `..`, a URL or a protocol in an argument is refused. An output file the command writes is one of the declared outputs. - outputs: [{"name": "out.mp4", "mime_type": "video/mp4"}]. Their files are uploaded and returned as Frameo links. - sidecars: optional small text files, e.g. an .ass subtitle file or a concat list [{"name": "list.txt", "content": "file 'a.mp4'\nfile 'b.mp4'"}]. - reason: one line on what this step is for, shown in the project's Frameo chat. 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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

run_ffmpeg

Save a sound from search_sound_effects into a Frameo project. Free: nothing is generated. sound_id: the id of a sound returned by search_sound_effects, where each result also carries an audio_url for listening to it before saving. project_id / module_id: the project and module to save it in, from list_projects. project_id is required; module_id is optional when the project has a single module. request_text: what the user asked for, in their words. It is shown in the project's Frameo chat. The sound is saved to the project's library and shown in its Frameo chat. While an ffmpeg, motion-graphics or media-analysis run is in progress in the module, the result carries frameo_chat "pending": the chat entry is added by read_project on the module after the run.

add_sound_to_library

Search Frameo's library of ready-made sound effects. Free, and nothing is spent. A library sound is instant and free, where generate_sound_effect costs credits and takes time. query: what the sound is, e.g. "door slam", "rain on a window". max_duration: seconds. 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.

search_sound_effects

Find voices for generate_speech in the user's Frameo voice library. Free. query: free words that rank the results, e.g. "warm narrator" or "gravelly villain". gender: "male" or "female". age: "young", "middle_aged" or "old". language: a name or code ("hindi", "hi"). accent: e.g. "indian", "british", "american". The filters 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.

search_voices

Show generations in one Frameo gallery card, by their ids. Free. Returns immediately. In chat apps that display Frameo cards, the card shows every generation passed, from one generate call or many: a placeholder with the time left while each one runs, then the image, video or audio once it is ready. It refreshes itself until all of them finish, without further tool calls. Where cards are not displayed, only the result below comes back. generation_ids: up to 24 generation or run ids, from any of the generate or run tools, shown in the order given. kind is as in get_task. The result is get_task's snapshot of those ids, without image previews.

show_generations

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.

switch_workspace

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. project_id / module_id: the project and module whose Library receives the files, from list_projects. Optional: without them the files are stored against the user's account only. module_id is optional when the project has a single module. 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.

show_upload

Make a video sharper and higher resolution. Spends the user's Frameo credits. video_url: a Frameo video link. duration: its real length in seconds (e.g. 5.04); it is priced per second, so do not round up. factor: 1.0 to 4.0, default 2 (a 480p clip becomes about 1080p tall). aspect_ratio and resolution: the values the source video was generated with. quote_id comes from estimate_cost(kind="upscale") for the same duration and project. confirmed_by_user records that the user agreed to the quoted credits. Upscaling is priced per second of video, and is normally the last step, applied to finished clips. request_text: what the user asked for, in their words. It is shown in the project's Frameo chat. 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. project_id / module_id: the project and module, from list_projects. project_id is required; module_id is optional when the project has a single module.

upscale_video

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_frameo_chat reports whether the result has been added to the project's Frameo chat. A result that finishes while a run is in progress in its module is added by a later get_task or wait_task on its ids.

wait_task