Flashloop

Permanently delete one of the user's videos by id. This cannot be undone, so do it only when the user asks to delete that video. Returns {deleted, video_id}. Example: {"video_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f"}.

flashloop_delete_video

Edit clips, voiceover takes, burned captions and music into one MP4 on a timeline; free, no credits. Use it to finish a video from parts you already have; to create new footage use flashloop_create_video. `clips` play in order with hard cuts; each is one of your completed videos (`video_id`, or its `video:<id>` job_id) or a Flashloop CDN `src`. A clip's slot is its own length unless `duration` is set; `fit` decides what a shorter clip does and `scale` how it fills the canvas. Anchors (`at`) place voice, captions and music: {clip: i} spans clip i, {clips: [i, j]} spans clips i through j, {start, end} are seconds on the output timeline. A take longer than its window is sped up to `max_speed`, then fails the job with VOICE_TOO_LONG unless `overflow` is 'trim'. A caption with `voice: k` follows take k, and when that take is a voice_generation_id its words are synced to the speech. Music ducks under the voice. `canvas.quality: 'preview'` renders a quick half-resolution draft for checking timing. Submitting an edited timeline again makes a new video and re-renders only the clips that changed. Returns {job_id, video_id, status, credits_used: 0, estimated_wait_seconds}; flashloop_wait_for_job returns the MP4 and `warnings` (such as a clip shorter than its slot). A failed job's message starts with a code such as VOICE_TOO_LONG, SOURCE_DOWNLOAD_FAILED or RENDER_FAILED that names what to change. flashloop_assemble_video is the simpler fixed-block form. Example: {"clips": [{"video_id": "video:<uuid>"}, {"video_id": "video:<uuid>"}], "voice": [{"voice_generation_id": "voice_generation:<uuid>", "at": {"clips": [0, 1]}}], "captions": [{"text": "Octopuses have three hearts.", "voice": 0}]}.

flashloop_edit_video

Estimate the credits a planned generation will cost, without running it or charging anything. Optional: use it when the user asks about price or before an expensive call, then compare the result with flashloop_get_credits; the server price is final and may differ slightly. Pass the same model and options you plan to send. kind 'video' and 'image' read the model's catalog pricing (`duration` accepts any whole second inside the model's `capabilities.duration` range; for a multi-shot video pass the total of all shot durations). kind 'voiceover' needs `text_characters` and prices it per character. kind 'music' is a flat price per song (1050 credits, 2000 with `max_mode`). kind 'assembly' (flashloop_assemble_video, flashloop_edit_video) is always 0. An upscale model returns `estimated_credits: null`: its price comes from the source file, so read credits_used from the finished job instead. Returns {estimated_credits (a number, or null when it cannot be known), basis, approximate, notes}. Example: {"kind": "video", "model": "kling-3.0", "duration": 10, "resolution": "1080p"}.

flashloop_estimate_cost

Register the finished video of one Faceless project in a single call. Pass exactly one of two forms. For a video rendered remotely with flashloop-motion-remote, pass the render_job_id (its printed jobId) alone: the render must be completed, whole (no --range) and at --quality final, and its video and thumbnail are taken from that render, so nothing is uploaded. For a video rendered in the project's sandbox (the /workspace of flashloop_exec with the same project_id), pass video_path and thumbnail_path once the final mp4 and thumbnail are written there: the files are checked and copied from the sandbox, so do not upload them with flashloop_upload_media first. The video must be an MP4 with H.264 video at 1080x1920 and an AAC audio track; the thumbnail a 1080x1920 JPEG or PNG under 10 MB. If anything is wrong, nothing is saved and the invalid_input error lists every problem with its exact fix: fix them all, then call once more. It also refuses with invalid_input when /workspace/brief.json, saved by flashloop_create_project, is missing, and says how to restore it. Returns {project_id, status: completed, video_url, thumbnail_url, studio_url, title}; studio_url opens the video in the user's Faceless Studio, so give it to the user. Safe to call again on a finished project. Examples: {"project_id": "0f8e2b9c-3a51-4d0e-9a7b-6c2d1e4f5a60", "render_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "title": "What if the moon were glass"}, or {"project_id": "0f8e2b9c-3a51-4d0e-9a7b-6c2d1e4f5a60", "video_path": "/workspace/what-if/moon/edit/renders/out.mp4", "thumbnail_path": "/workspace/what-if/moon/thumbnail.jpg", "title": "What if the moon were glass"}.

flashloop_finish_video

Generate a full song with Flashloop Music, with vocals or instrumental, from a description (mode 'simple') or from your own style and lyrics (mode 'custom'). Use it for background music or a song the user asks for; spoken narration is flashloop_generate_voiceover instead. Every generation makes two different tracks, each as an mp3 preview and a wav download. Costs 1050 credits, or 2000 with max_mode, both tracks and wav files included. Returns {job_id, kind: 'music', status, credits_used, credits_remaining}; flashloop_wait_for_job then returns `output.tracks`: [{index, mp3_url, wav_url, title, duration_seconds}]. Example: {"mode": "simple", "prompt": "calm lo-fi beat for a study video", "instrumental": true}.

flashloop_generate_music

Turn a script into speech with one voice, or a two-speaker dialogue, and return a `job_id`. Use it for narration and voiceover takes; to re-voice existing audio use flashloop_change_voice, and to translate speech use flashloop_translate_audio. Pick `voice_id` from flashloop_list_voices: a voice tagged with a `model` works only with that `model_id`, and a voice without one works only with the eleven models. Models: eleven-v3-voiceover (default; up to 5000 characters; cloned voices), eleven-v4-voiceover (most expressive, audio tags such as [whispered]; up to 10000; cloned voices; `stability`, `language_code`), eleven-v4-turbo-voiceover (faster, half the price; up to 10000; `stability`, `language_code`), gemini-3-1-voiceover (70+ languages, half the price; up to 10000), gemini-3-8-flash-voiceover and gemini-3-8-flash-lite-voiceover (up to 5000 spoken characters; the text is read literally, so delivery goes in `style`; accepted tags <laugh>, <sigh>, <short pause>, <breath>, <cough>; a dialogue sends `speakers` and `turns` instead of `text` and `voice_id`). Spends credits per character (price: flashloop_estimate_cost kind 'voiceover' with text_characters). Returns {job_id, kind, status, credits_remaining}. Generation takes from seconds to several minutes with the script length: flashloop_wait_for_job returns the audio in `output.url`, word timings in `output.words` and the length in `output.raw.duration_seconds`. Pass the job_id as `voice_generation_id` to flashloop_edit_video for captions synced to the speech. A result that already has `audio_url` is finished and has no job. Example: {"text": "Did you know octopuses have three hearts?", "voice_id": "<id from flashloop_list_voices>", "model_id": "eleven-v4-voiceover", "stability": 0.45, "language_code": "en"}.

flashloop_generate_voiceover

Read the Flashloop Faceless video guide before making a video. Call it first: it explains the full flow with flashloop_list_styles, flashloop_create_project, flashloop_exec, flashloop_generate_voiceover and flashloop_finish_video. Without `path` it returns the main instructions and the list of extra files. With `path` it returns that one file as text. Example: {"path": "references/what-if-voiceover.md"}.

flashloop_get_instructions

Turn a generation's cdn.flashloop.app URL (the `url` of a flashloop_list_generations row or flashloop_wait_for_job output) into a time-limited direct-download URL (Content-Disposition: attachment, expires in about 1 hour). Use it when the user wants to SAVE a video, image or voiceover to their device; to just show it, use the cdn URL itself. Returns {download_url, expires_in_seconds}: give download_url to the user. Calls the Flashloop API (https://www.flashloop.ai/mcp). Example: {"url": "https://cdn.flashloop.app/videos/123/1730000000000_out.mp4", "filename": "moon.mp4"}.

flashloop_get_download_url

Check one async Flashloop job once, without waiting, and return its state. Use it to peek at a job while doing other work; to block until it finishes, use flashloop_wait_for_job. Returns the same shape as flashloop_wait_for_job: status 'completed' with `output`, 'failed' with `error`, or 'timeout', which here means the job is still running. Example: {"job_id": "image:7d2e4f10-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}.

flashloop_get_job

Return the user's current credit balance as {credits_balance}, a whole number of credits. Use it before a paid generation to check that the balance covers the price from flashloop_estimate_cost, or after a batch to see what it spent. Takes no input, costs nothing and changes nothing. For the account email and plan, use flashloop_whoami.

flashloop_get_credits

Show the Faceless video styles as a gallery the user can pick from, and return them as {styles: [{id, title, summary, preview_url, thumbnail_url, reference_video_url}]}. Free. This list is the one source of style ids: after the user picks one, pass its `id` as `style_id` to flashloop_create_project. Takes no arguments: {}.

flashloop_list_styles

List the user's past videos and images, newest first, and show them as a gallery. Use it for history requests (show my videos, find the image I made yesterday) and to get the id or URL of an earlier result: a completed `url` can be passed as a reference to flashloop_create_image or flashloop_create_video, and `id` is the video_id or image_id for flashloop_delete_video, flashloop_delete_image or flashloop_edit_video. Voiceovers, music and saved references are not listed here (saved references: flashloop_list_references). A generation made in this conversation is already shown by its own card, so do not list it again. Returns {generations: [{job_id, kind, id, status, url, thumbnail_url, output_urls, model_name, created_at, failure_category}], page, limit, has_more}; when has_more is true, call again with page + 1. Example: {"type": "video", "status": "completed", "limit": 9}.

flashloop_list_generations

List the video, image, upscale and music models with their ids, pricing and a `capabilities` block. Call it before flashloop_create_video, flashloop_create_image, flashloop_upscale, flashloop_generate_music or flashloop_estimate_cost to pick a valid model id and learn which options that model accepts; pass `type` to list one kind only, which keeps the result short. Voiceover models are not listed here: they are the `model_id` values of flashloop_generate_voiceover. Read every limit from `capabilities`: `duration` (mode "range" accepts any whole second from min_seconds to max_seconds and `values` are only presets; mode "enum" accepts only `values`), `max_reference_images`, `reference_support` (reference video and audio caps), `supports_characters` and `character_cap` (saved references), `requires_first_frame`, `multi_shot`, `draft_support`, upload limits (`max_image_size_mb`, `max_video_size_mb`, `accepted_upload_formats`) and `typical_seconds` (usual render time). The top-level `supported_durations` is a legacy preset list; `capabilities.duration` wins. Returns {models: [{id, name, type, description, supported_aspect_ratios, supported_resolutions, defaults, pricing, capabilities}]}. Example: {"type": "video"}.

flashloop_list_models

List the saved references the user can attach to a generation: characters (people), locations (places) and elements (objects and props), from both the curated public library and the user's own rows (`owned_by_me`). Use it when the user mentions a saved character, place or object, or asks what they have saved; a subject with no saved reference is simply described in the prompt. Pass a row's `id` to flashloop_create_image or flashloop_create_video in the field for its kind: `character_ids`, `location_ids` or `element_ids`. A wrong field attaches nothing, with no error, and the render still costs full price. Copy ids from rows; never derive them from a name. Only rows with status 'ready' can be attached. The library cannot be paged server-side, so narrow it with `kind`, `search` and `owner`; `counts`, `total_matched` and `truncated` show what was left out. Shows the rows as a gallery card. Returns {references: [{id, kind, name, description, image_url, status, owned_by_me, origin, role, category, usage_count, variant_of}], universes, counts, total_matched, truncated, warnings}. Example: {"kind": "character", "owner": "me", "search": "ana"}.

flashloop_list_references

List the voices the user can speak with: built-in presets and the user's own cloned voices. Call it before flashloop_generate_voiceover, flashloop_change_voice or flashloop_translate_audio to get a valid `voice_id`. A voice with a `model` field (gemini-3-1-voiceover, gemini-3-8-flash-voiceover, gemini-3-8-flash-lite-voiceover) works only with that flashloop_generate_voiceover model_id; a voice without one works only with the eleven models; cloned voices (owner 'user') never work with the gemini models. Takes no input and costs nothing. Returns {voices: [{id, name, description, preview_audio_url, status, owner ('builtin' or 'user'), model, gender}]}; play preview_audio_url to let the user choose.

flashloop_list_voices

Open an interactive upload widget where the user picks one or more reference images from their device. Use it when the image is only on the user's device or in a chat attachment you cannot reach, or when the curl `command` of flashloop_upload_media is blocked; a file in the Flashloop sandbox goes through flashloop_upload_media `sandbox_path` instead. `model_id` (from flashloop_list_models) sets the widget's limits: how many images, accepted formats and max file size for that model. Each file is uploaded and moderated immediately; when the batch finishes the widget posts all resulting URLs into the conversation by itself (a 'Done' button appears only when the host refuses that post). Pass those URLs in `reference_image_urls` of flashloop_create_image or flashloop_create_video. Images only; a video or audio reference goes through flashloop_upload_media. Returns {message, max_files, max_bytes, accepted, model_reference_max, session}; wait for the URLs the widget posts. Example: {"model_id": "nano-banana-pro"}.

flashloop_upload_widget

Rename one of the user's own saved references, change a character's `role` or an element's `category`. Curated library rows and other people's rows cannot be edited. The picture cannot be changed: a different look is a new reference, saved with flashloop_upload_reference. Send at least one of name, role or category. Returns {reference: row as in flashloop_list_references}. Example: {"kind": "character", "reference_id": "<id from flashloop_list_references>", "name": "Detective Ana"}.

flashloop_update_reference

Run a bash command in a persistent Linux sandbox for building media and documents. /workspace keeps its files between calls; pass a `project_id` from flashloop_create_project to work in that video project's own sandbox, or leave it out for the general one. Preinstalled: bash, curl, git, jq, zip, ffmpeg and ffprobe, Node.js with npm, Bun, Python 3 with pillow, matplotlib, pandas, openpyxl, python-docx, python-pptx, reportlab, pypdf and faster-whisper, and `flashloop-motion`, which renders JSX motion scenes to mp4 (run `flashloop-motion --help`). The network reaches package registries, web fonts and the Flashloop CDN only: register any other public file with flashloop_upload_media `url` and download the returned url here. To hand a file made here to the user or to a generation, call flashloop_upload_media with `sandbox_path` (and the same `project_id`); a finished Faceless video goes to flashloop_finish_video by path. Foreground commands wait up to `timeout_seconds` (120 at most); longer work goes in `background`. Returns {exit_code, stdout, stderr, timed_out, truncated, sandbox_created, project_id}; sandbox_created true means a fresh sandbox, so earlier files are gone. Example: {"command": "ffprobe -v error -show_entries format=duration -of csv=p=0 out.mp4", "project_id": "0f8e2b9c-3a51-4d0e-9a7b-6c2d1e4f5a60"}.

flashloop_exec

Save an image the user already has as a reusable reference: a person (kind 'character') or an object or prop (kind 'element'). Free and instant: nothing is generated, and the row comes back ready to use. Use it to keep a portrait or object the user liked, for example right after flashloop_create_image. A character needs a `name` (how the user will refer to them) and exactly one image. Elements save a batch of up to 20 images in one call, each named and filed automatically; every image is moderated and one blocked image rejects the whole batch. There is no upload path for places: generate one with flashloop_create_reference. A chat attachment or a sandbox file must first be uploaded with flashloop_upload_media; pass the URL it returns. Returns {references: [rows as in flashloop_list_references], created}; pass a row's `id` in `character_ids` or `element_ids` of flashloop_create_image or flashloop_create_video. Example: {"kind": "character", "image_urls": ["https://cdn.flashloop.app/...png"], "name": "Ana", "role": "The detective"}.

flashloop_upload_reference

Translate the speech in an audio file into another language (dubbing). The translation always keeps the source speaker's voice; for another voice, pass the translated `output.url` to flashloop_change_voice next. Use it when the user wants existing speech in another language; to speak a new script use flashloop_generate_voiceover with a translated `text`. Send the exact `duration_seconds` of the audio; that field says where to get it, never estimate it. Spends credits per second. Returns {job_id, kind: 'translate', status}; call flashloop_wait_for_job for the translated audio in `output.url`. Example: {"audio_url": "https://cdn.flashloop.app/...mp3", "target_language": "es", "duration_seconds": 42}.

flashloop_translate_audio

Bring a media file into Flashloop and return its `url`, which flashloop_create_image and flashloop_create_video accept in `reference_image_urls` and flashloop_create_project accepts as `reference_url`. Pick the input by where the file is: (1) a file in the Flashloop sandbox, made or processed with flashloop_exec (a chart, a frame, an edited clip): pass `sandbox_path` and, if the file was made under a project, the same `project_id`; one call copies it server-side, registers and moderates it. A finished Faceless video goes to flashloop_finish_video instead. (2) a direct public URL of a media file that needs no processing: pass `url` with `kind` and `content_type`. To process a public file, register it this way first and download the returned `url` inside flashloop_exec: the sandbox reaches only the Flashloop CDN and package registries. (3) a file only in the chat's own code-execution environment, such as an attachment written there: pass `filename` + `content_type`, run the returned curl `command` there, then call this tool again with `url` set to the returned `public_url`, `kind` and `content_type`. When that environment blocks the curl, use flashloop_upload_widget. (4) files the host passes as file parameters arrive in `files`. (5) a tiny file (up to 100KB) with no other way in: `base64` + `content_type`; base64 is written token by token, so it stalls above ~100KB and fails past 500KB. With a `project_id` from flashloop_create_project the registered file is also filed under that Faceless project; a `sandbox_path` file uploaded that way stays in the project and out of the user's Uploads library. Returns {asset_id, url, moderation_status, ...}: `files` returns {assets, failed} and `filename` returns {upload_url, public_url, command, next_step}. Uploaded media is moderated; rejected media cannot be used. Calls the Flashloop API (https://www.flashloop.ai/mcp). Example: {"sandbox_path": "/workspace/charts/revenue.png"}.

flashloop_upload_media

Upscale an existing image or video 2x or 4x for a sharper, larger file, without generating new content. Use it when the user asks to enhance, upscale or enlarge a file they already have; to make a new image or video use flashloop_create_image or flashloop_create_video. Pick `model_id` from flashloop_list_models type 'upscale': its `upscale_input_type` says whether it takes an image or a video, and the source must match. `source_url` must be a reachable https URL; a chat attachment or a sandbox file must first be uploaded with flashloop_upload_media, and the URL it returns goes here. Spends credits, priced from the source's real duration or resolution, so no estimate exists up front: compare credits_remaining before and after, or read credits_used from the finished job. Returns {job_id, kind, id, status, credits_remaining, estimated_wait_seconds}; call flashloop_wait_for_job for the upscaled file's URL. Example: {"model_id": "topaz-image-upscale", "source_url": "https://cdn.flashloop.app/...png", "upscale_factor": "2"}.

flashloop_upscale

Wait for one async Flashloop job to finish and return its result. Every tool that starts work returns a `job_id` (flashloop_create_image, flashloop_create_video, flashloop_generate_voiceover, flashloop_generate_music, flashloop_upscale, flashloop_assemble_video, flashloop_edit_video, flashloop_change_voice, flashloop_translate_audio, flashloop_create_reference); pass it here when the next step needs the output. It waits up to `timeout_ms` (default 90000, 90 seconds). Videos often take several minutes, so a result with status 'timeout' means the job is still running, not that it failed: call this tool again with the same job_id, which costs nothing and loses nothing. Returns {status: 'completed', job_id, output: {url, urls (every image), thumbnail_url, tracks (music: mp3_url, wav_url, title, duration_seconds), words (voiceover word timings in seconds), raw: {credits_used, duration_seconds, warnings, ...}}}, or {status: 'failed', job_id, error: {error, message}}, or {status: 'timeout', job_id, waited_ms, hint}. The create tool's card already shows progress to the user. For one check without waiting, use flashloop_get_job. Example: {"job_id": "video:3f1c9a2e-8b7d-4c1a-9e2f-5d6b7a8c9d0e"}.

flashloop_wait_for_job

Return the signed-in Flashloop account: its email, credit balance and subscription plan. Use it to confirm which account is connected or to answer a question about the plan. For the balance alone before a paid call, flashloop_get_credits is enough. Takes no input and changes nothing. Returns {email, credits_balance, subscription: {tier, status, current_period_end} or null when there is no plan}.

flashloop_whoami