Skip to main content
Glama

Sonilo MCP Server

An MCP (Model Context Protocol) server that exposes Sonilo's licensed music and sound-effects API to MCP-compatible clients (Claude Code, Claude Desktop, Codex).

The flagship tool is video_to_music: hand it your finished video and it composes an original soundtrack matched to the cut — the music follows the pacing, emotion, and edits because the model saw them. Length matches the video automatically. Every track is licensed and safe for commercial use (terms apply). text_to_music is also available for fixed-length tracks with no video to match.

For sound design, video_to_sfx watches your video and generates matching sound effects, returned as a standalone audio file. text_to_sfx generates a standalone effect from a description.

▶ Example result — an AI-generated trailer with its soundtrack composed by video_to_music from the assembled cut. For recipes covering any AI-video pipeline (stitch → grade → add music → mux), see the Sonilo video-to-music cookbook.

Quickstart with Claude Code

Sign in once with the CLI, then add the server with no secret in the config:

npm install -g sonilo-cli && sonilo login
claude mcp add sonilo -- uvx sonilo-mcp

Or hold an API key yourself — get one from the Sonilo dashboard:

claude mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp

Then start a session and ask, e.g. "Make background music that matches this video: ~/Desktop/promo.mp4."

Related MCP server: Spotify MCP Server

Why Sonilo

  • Video-to-music — give it a video and Sonilo composes a full-length score matched to its pacing, motion, and emotion. Transitions and beat drops align to your cut points, and the track matches the video's duration exactly — no prompts or manual syncing required.

  • Text-to-music — generate tracks from a text description (genre, mood, tempo, instrumentation), at an exact duration (5–360s) or none at all, in which case Sonilo picks a length that suits the prompt.

  • Video-to-SFX — Sonilo watches the video and generates sound effects for what it sees. You get the SFX as a standalone audio file. Optional segments let you script effects to specific time ranges ([{start, end, prompt}]).

  • Text-to-SFX — generate a standalone sound effect from a description (0.5–180s), in wav, mp3, aac, or flac.

  • Proofread before dubbing — proofread transcribes a video and translates the transcript into editable .srt files, one per language plus the source-language transcript. Read and correct the wording, then hand the files to dubbing as subtitles so the dub speaks exactly the approved text — nothing is voiced until you have signed off on it.

  • Fully licensed, commercial-safe — music licensed via Shutterstock; every generated track is cleared for commercial use on social, brand content, and advertising, with no Content ID worries.

  • Video-to-sound — generate music and sound effects for the same clip in one call, mixed into a single balanced soundtrack. Get back the mixed audio, or a new video with it muxed in.

  • Multiple variants per call — text_to_music, video_to_music, video_to_video_music, video_to_sound, and video_to_video_sound accept variants_num (1–10, default 1): generate several distinct creative directions in one request instead of re-rolling one at a time. Cost scales linearly with N, and N > 1 is never covered by the free trial.

  • Instrument stems — text_to_music and video_to_music accept stems=true: get the generated track additionally split into drums, bass, vocals and other, at no extra charge. Separation adds a few minutes; on video_to_music it splits the generated music, never the video's own audio.

  • Pay as you go — billed only for the seconds of music you generate. Self-serve accounts start with free runs on every endpoint, no card required: 2 each on text-to-music, text-to-sfx, audio-ducking and proofread, and 1 each on video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound and video-to-video-sound. After that, calls bill at the normal rate. dubbing gets one free run, a 15-second preview: the first single-language call without subtitles dubs only the first 15 seconds of the video. After that it bills video duration × number of languages (see Free trial below).

Audio Playback Dependencies

The play_audio tool requires PortAudio at runtime (for sounddevice). On macOS/Linux, install via:

  • macOS: brew install portaudio

  • Debian/Ubuntu: sudo apt-get install libportaudio2

uvx sonilo-mcp and pip install will pull the Python bindings, but the system PortAudio library must be installed separately. The other tools (text_to_music, video_to_music, text_to_sfx, video_to_sfx, audio_ducking, get_sfx_task, get_account_services, get_usage) work without PortAudio.

Quickstart with Claude Desktop

  1. Authenticate, either way round:

    • Sign in with the CLI — npm install -g sonilo-cli && sonilo login — and leave "env": {} below. Nothing secret goes in the config file.

    • Or get an API key from the Sonilo dashboard and put it in "env".

  2. Install the uv package manager (provides uvx):

    curl -LsSf https://astral.sh/uv/install.sh | sh

    See the uv repo for other install methods.

  3. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

    {
      "mcpServers": {
        "sonilo": {
          "command": "uvx",
          "args": ["sonilo-mcp"],
          "env": {}
        }
      }
    }

    That is the whole config when you have signed in with sonilo login. To hold a key instead, or to change the defaults:

    "env": {
      "SONILO_API_KEY": "sk-...",
      "SONILO_API_URL": "https://api.sonilo.com",
      "TIME_OUT_SECONDS": "600"
    }
  4. Restart Claude Desktop. You should see the Sonilo tools available in the tool menu.

Quickstart with Codex

Signed in with the CLI (npm install -g sonilo-cli && sonilo login), the whole setup is one command:

codex mcp add sonilo -- uvx sonilo-mcp

Or, holding a key yourself:

codex mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp

To configure it by hand instead:

  1. Get your API key from the Sonilo dashboard — or skip this step if you signed in with sonilo login.

  2. Install the uv package manager (provides uvx):

    curl -LsSf https://astral.sh/uv/install.sh | sh
  3. **Go to Codex > Settings > MCP servers to fill out the following:

alt text

Or you can add the server** to ~/.codex/config.toml:

[mcp_servers.sonilo]
command = "uvx"
args = ["sonilo-mcp"]

# Omit this whole block when you have signed in with `sonilo login`.
[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk-..."
SONILO_API_URL = "https://api.sonilo.com"
TIME_OUT_SECONDS = "600"
  1. Restart Codex (or start a new session), then run /mcp to confirm sonilo is connected and its tools are listed.

Example usage

Once the server is connected, just ask your assistant in natural language. For example:

  • "Make background music that matches this video: ~/Desktop/promo.mp4."

  • "Compose music for https://example.com/clip.mp4 with a calm, ambient style."

  • "I stitched my AI-generated clips into ~/Desktop/trailer.mp4 — add a soundtrack that matches the cut."

  • "Use Sonilo mcp to generate 30 seconds of upbeat lo-fi hip-hop for a study playlist and save it to my Desktop."

  • "Use Sonilo to write an epic orchestral cinematic track, about 60 seconds long."

  • "What Sonilo services and limits does my account have?"

  • "Show my Sonilo usage for the last 7 days."

  • "Play the track you just generated."

The assistant will call the matching tool (text_to_music, video_to_music, text_to_sfx, video_to_sfx, audio_ducking, get_sfx_task, get_account_services, get_usage, or play_audio) and save generated audio to your configured output directory.

Configuration

Authentication

The server takes its key from SONILO_API_KEY if that is set, and otherwise from the credential written by sonilo login (~/.config/sonilo/credentials.json, or $XDG_CONFIG_HOME/sonilo/). The environment variable wins on purpose, so any config that already sets it keeps resolving to the same account after an upgrade.

The credential is looked up by the server's own SONILO_API_URL, so a staging server never picks up a production sign-in. This server only ever reads the file: run sonilo login again to renew it (keys from a sign-in expire after 90 days) and sonilo logout to revoke it.

Environment Variables

Variable

Default

Description

SONILO_API_KEY

(from sonilo login)

Bearer token. Required only if you have not signed in with the CLI.

SONILO_API_URL

https://api.sonilo.com

Public API base URL.

SONILO_MCP_BASE_PATH

~/Desktop

Default output directory and base for relative input paths. Also the confinement boundary (see below).

SONILO_MCP_ALLOW_ANY_PATH

false

Set to true to let tools read/write files outside SONILO_MCP_BASE_PATH.

TIME_OUT_SECONDS

600

Timeout, in seconds, for streaming music (text_to_music, and video_to_music without preserve_speech), uploads and downloads. Aligned with the backend's streaming read timeout. Task-based tools (sound effects, ducking, video-to-video, async music, analyze_video, proofread) wait at least 2700s (45 min) for their task whatever this is set to, because the backend lets a task wait up to 2400s in its queue; set it higher to wait longer. stems waits at least 75 min and dubbing at least 2 hours.

Some MCP hosts impose their own tool-call timeout and may cut a call off before that wait ends. The task keeps running and is still billed: its id is in the server's stderr log as [sonilo-mcp] task submitted: <id>, and get_sfx_task("<id>") retrieves the result — nothing is lost.

File access & confinement

By default, the file tools (video_to_music input, play_audio, and any output_directory) are confined to SONILO_MCP_BASE_PATH. Paths that resolve outside it (after symlink resolution) are rejected. This limits the blast radius if a client is tricked into reading or exfiltrating arbitrary files. To opt out — e.g. to read a video from elsewhere on disk — set SONILO_MCP_ALLOW_ANY_PATH=true.

Tools

Tool

Description

Cost

text_to_music(prompt, duration?, output_format?, variants_num?, stems?, output_directory?)

Generate music from a text prompt. variants_num (1–10, default 1) generates that many distinct variants in one request, each with its own title; N > 1 forces the backend's async mode automatically and is never covered by the free trial. stems (default false) also saves the track split into four separate instrument tracks — drums, bass, vocals and other — at no extra charge; it adds a few minutes (the call waits up to 75 min) and forces the backend's async mode automatically. A stems_error note in the result means only the free separation failed or was skipped — the music itself is fine.

✅

video_to_music(video_path? | video_url?, prompt?, preserve_speech?, variants_num?, prompt_influence?, stems?, output_directory?)

Generate music matched to a video. Max duration 360s (6 min); subject to the account's upload-size cap (typically 300 MB). preserve_speech (default false) keeps the source speech in the result — you also get a vocals speech stem and a ready-to-use mux; when set, the call runs the backend's async generation mode internally instead of streaming. variants_num (1–10, default 1) works the same as text_to_music's. prompt_influence (0–1, API default 0.5) sets how strongly the generated music follows the prompt; omit it unless you want stricter or looser prompt adherence. Free, and works in both the streaming and async modes. stems (default false) works the same as text_to_music's — it splits the generated music, never the video's own audio.

✅

text_to_sfx(prompt, duration?, audio_format?, output_directory?)

Generate a sound effect from text. Duration 0.5–180s, optional — omit it for Sonilo's own default length; formats wav/mp3/aac/flac (default aac).

✅

video_to_sfx(video_path? | video_url?, prompt?, segments?, audio_format?, output_directory?)

Generate SFX for a video; saves the generated SFX audio. Max video duration 480s (8 min).

✅

video_to_video_music(video_path? | video_url?, prompt?, segments?, keep_original_sound?, ducking?, preserve_speech?, variants_num?, prompt_influence?, output_directory?)

Generate music for a video and return a new .mp4 with it muxed in. By default the result's audio is the generated music alone — the source's own audio is removed. Pass keep_original_sound=true to keep the whole source track with the music statically mixed under it, adding ducking=true to dip the music under the voice instead; or preserve_speech=true to keep only the isolated speech. keep_original_sound supersedes preserve_speech. Input must carry H.264/HEVC/VP9/AV1 (mp4, mov, m4v, webm); animated gif and VP8 webm are rejected. Max video duration 360s (6 min). variants_num (1–10, default 1) saves one .mp4 per variant. prompt_influence (0–1, API default 0.5) sets how strongly the generated music follows the prompt; omit it unless you want stricter or looser prompt adherence. Free.

✅

video_to_video_sfx(video_path? | video_url?, prompt?, segments?, output_directory?)

Generate SFX for a video and return a new .mp4 with them muxed in. Max video duration 480s (8 min).

✅

video_to_sound(video_path? | video_url?, music_prompt?, sfx_prompt?, segments?, preserve_speech?, ducking?, output_format?, variants_num?, output_directory?)

Generate music and SFX for a video in one call and save the mixed audio track. One charge instead of two, with the two layers balanced by the backend. ducking (default false) brings the source video's own speech into the mix and dips the music under it — leave it off and the result is the generated music and effects alone, with no music_processed stem. output_format (wav default, m4a, or mp3 at 320 kbps) sets the combined track's container; the music and SFX stems keep their native formats. Max video duration 480s (8 min). variants_num (1–10, default 1) saves one mixed track per variant.

✅

video_to_video_sound(video_path? | video_url?, music_prompt?, sfx_prompt?, segments?, keep_original_sound?, preserve_speech?, ducking?, variants_num?, output_directory?)

Like video_to_sound, but returns a new .mp4 with the mixed soundtrack muxed in. By default the result's audio is the generated music and effects alone — the source's own audio is removed, so the result also carries no music_processed stem. Pass keep_original_sound=true to keep the whole source track (statically mixed; add ducking=true to duck it under the mix instead), or preserve_speech=true for the isolated speech only. keep_original_sound is accepted only here, not by video_to_sound. Max video duration 480s (8 min). variants_num (1–10, default 1) saves one .mp4 per variant.

✅

dubbing(video_path? | video_url?, languages?, ducking?, lipsync?, subtitles?, export_srt?, output_directory?)

Dub a video into other languages and save one dubbed .mp4 per language. languages is a list of codes (en, zh_cn, ja, ko, pt, pt_br, es, es_419, de, fr, it, ru, th, ar, tr, vi, id, ta, ml, kn, gu, pa_in, sd_in, hi); omit it for the default ["zh_cn", "es", "fr"]. pt_br is Brazilian Portuguese and es_419 Latin American Spanish; plain pt and es stay unqualified, as does ar. pa_in and sd_in are Punjabi and Sindhi as spoken in India, the only variants available; hi is Hindi. video_url must be https — the dubbing pipeline fetches the source itself. lipsync defaults to true: the speaker's mouth is re-rendered to match the dubbed speech. Set lipsync=false to leave the picture completely untouched instead — the video comes back at its original resolution and frame rate rather than re-rendered, and only the audio is replaced, so the mouths keep moving to the original language; useful for footage with no on-camera speaker. subtitles is one script per target language — {"es": "/path/es.srt", "fr": "https://.../fr.vtt"}, a local .srt/.vtt path or an https URL — carrying the lines to be spoken in that language, used instead of the pipeline's own translation; the keys must match the languages being dubbed. export_srt (needs subtitles) also returns a re-timed .srt per language, aligned to the delivered audio with the lines kept verbatim. Max video duration 300s (5 min). Billed per language. The first single-language call without subtitles is a free 15-second preview (see Free trial below).

✅

proofread(video_path? | video_url?, languages?, source_language?, output_directory?)

Transcribe a video and translate its script into the target languages, saving one editable .srt per language plus the source-language transcript. Nothing is dubbed and nothing is spoken — this is the step before dubbing: correct the wording, then pass the files to dubbing as subtitles. languages takes the same codes as dubbing; omit it, or pass [], for the source-language transcript alone. source_language is an optional hint for transcription — without it the language is detected, and the detected code is reported either way. video_url must be https, and the video must have an audio track. Max video duration 300s (5 min). Billed per language (a transcript-only request counts as one), with a 10-second billing floor.

✅

analyze_video(video_path? | video_url?, prompt?, variants_num?, mode?)

Analyze a video and return a creative brief — a time-aligned segments plan plus one ready-to-use generation prompt per variation. mode defaults to both, which adds a sound-design brief (sfx_segments plus a single sfx_prompt) next to the music one; music or sfx returns just that one brief, at the same price. Generates nothing and writes no file: the brief comes back inline as JSON, to feed straight into video_to_music, video_to_sfx, video_to_sound or their video-to-video counterparts. Use it when you do not yet know what the video should sound like. Max video duration 480s (8 min); variants_num is 1–5 (default 1) and is billed per brief, with a 10-second billing floor.

✅

audio_ducking(voice_path? | voice_url?, music_path? | music_url?, output_directory?)

Duck a music bed under a voice track. The voice input may be a video — the ducked mix is muxed back into a new .mp4. Each input max 360s (6 min); subject to the account's upload-size cap.

✅

get_sfx_task(task_id, output_directory?)

Check an SFX, audio-ducking, video-to-video, video-to-sound, dubbing, proofread, video-analysis, or async video-to-music task and return its result — recovery for timed-out text_to_sfx, video_to_sfx, audio_ducking, video_to_video_music, video_to_video_sfx, video_to_sound, video_to_video_sound, dubbing, proofread, analyze_video, and video_to_music(preserve_speech=true) calls. An analyze_video task has no file to download, so its brief comes back inline; a proofread task saves its .srt files the same way a direct call would; everything else is saved to disk.

❌

get_account_services()

List available services, limits, and the free-trial allowance left per service.

❌

get_usage(days=30)

Show usage summary + per-day breakdown.

❌

play_audio(input_file_path)

Play a local audio file.

❌

Tools marked ✅ make API calls that incur charges on your Sonilo account.

Every tool also carries MCP tool annotations, so clients can tell the two kinds apart without reading descriptions: get_account_services, get_usage and play_audio are read-only; every other tool writes files or incurs charges, and none of them is destructive (outputs never overwrite an existing file). The server's instructions tell an agent to check get_account_services before the first paid call and to recover a timed-out call with get_sfx_task.

Free trial: self-serve accounts start with a few free runs per service — no card required. get_account_services() reports what is left as trial[service] = {granted, used, remaining}; check it before calling a ✅ tool so you can warn the user instead of failing on them. When a service's remaining hits 0, calls to it fail with trial_exhausted until a payment method is added. Dubbing's single free run is a 15-second preview: the first single-language call without subtitles translates only the first 15 seconds of the video, free, and the result carries trial_preview with what the full video would cost; proofread has 2 free runs, and like dubbing it bills per language. Accounts without a free-trial allowance simply have no trial key.

Optional: if ffprobe (part of FFmpeg) is installed, video_to_music checks a video's duration locally and rejects anything over 360s before uploading. video_to_sfx performs the same local check with its 480s cap. audio_ducking does the same for both of its inputs against its 360s cap. Without it, the same limits are still enforced by the backend.

Sound effects and ducking run as tasks

The music tools stream their result and finish in one call — with one exception: video_to_music(preserve_speech=true) submits a task and polls it internally instead, because keeping the source speech is only available in the backend's async mode. You still get the saved file paths back from a single call; you just don't see the task, and — like the SFX tools — it uses the same get_sfx_task recovery path if the call times out. The SFX tools submit a task, then poll it until it completes — text_to_sfx and video_to_sfx do this for you and return the saved file paths, so you normally never see the task. audio_ducking uses the same submit-then-poll flow and the same get_sfx_task recovery path.

If a call times out, the generation keeps running (and is already charged). The error message carries the task id, and get_sfx_task("<id>") retrieves the result once it's ready. The task id is also printed to stderr the moment a task is submitted, so it survives even a cancelled call. get_sfx_task is safe to call repeatedly: if the file is already on disk it reports that instead of downloading a second copy.

Output Format

Music is saved as .m4a (AAC in MP4 container). File names use the title returned by the backend (slugified), or a sonilo-<timestamp>.m4a fallback. When multiple parallel streams are returned, a -<index> suffix is appended.

video_to_music(preserve_speech=true) saves up to three kinds of file, each labeled in the returned text: the generated music audio (same naming as above, based on prompt or falling back to music-<first 8 chars of the task id>), the preserved speech stem as <base>-vocals.<ext>, and the mux — speech and music already mixed together, the ready-to-use combined result — as <base>-mux.<ext> (or <base>-mux-<index>.<ext> for multiple streams). The speech stem and mux extensions come from the backend's reported content_type (typically .m4a).

Sound effects are saved in the requested audio_format — wav, mp3, flac, or aac (the default, written as .m4a); video_to_sfx saves audio only, not the source video.

Combined sound (video_to_sound / video_to_video_sound) is saved as a single file: a .wav for video_to_sound, a .mp4 for video_to_video_sound. The name comes from music_prompt, falling back to sfx_prompt and then to sound-<first 8 chars of the task id> / v2v-sound-<first 8 chars of the task id>. The separate music and SFX stems stay on the backend — only the mixed result is downloaded.

Multiple variants (variants_num > 1 on text_to_music, video_to_music, video_to_video_music, video_to_sound, video_to_video_sound) save one file per variant instead of one, suffixed -0, -1, … in request order (e.g. <base>-0.m4a, <base>-1.m4a). For the music tools, each variant is its own creative direction and the returned text names it when the backend provides a title. Cost scales linearly with variants_num, and any value above 1 is billed in full even on a free-trial account. A timed-out multi-variant call recovers all of its variants through get_sfx_task, the same as a single-variant one.

Stems (stems=true on text_to_music / video_to_music) save four extra files per generated stream — <base>-stems-drums.<ext>, -stems-bass, -stems-vocals, -stems-other (with the variant index folded in as <base>-stems-<index>-<name>.<ext> when variants_num > 1) — alongside the untouched full track. Separation is free and best-effort: it typically adds 2–6 minutes (the call waits up to 40), and when it fails or is skipped the result carries a stems_error note instead of (or alongside a partial set of) stem files, while the music itself is unaffected and fully delivered.

Dubbing (dubbing) is saved as one .mp4 per requested language, named dubbing-<first 8 chars of the task id>.<language>.mp4 — there is no prompt to name the files after. With export_srt, each language's re-timed script lands beside its video as dubbing-<first 8 chars of the task id>.<language>.srt, reported with that language's export status and alignment loss (plus its issue codes and report link when the export was blocked). Every dubbed .mp4 is downloaded before the first .srt, and a script that was blocked or could not be downloaded is reported as a note, not a failure — a missing subtitle never costs you a video. Asking for four languages writes four files and costs four times as much as one. Dubbing polls for at least two hours regardless of TIME_OUT_SECONDS, matching the backend's own ceiling for the job.

Proofread (proofread) is saved as one .srt per language in the result, named proofread-<first 8 chars of the task id>.<language>.srt — there is no prompt to name the files after. The set always includes the detected source language on top of every requested target, so even a request with no languages writes one file. After the files, the returned text reports the detected source_language and the cue_count of the source script, then one note per non-blocking warning (e.g. a cue whose text runs too fast to read) — a warning never blocks a file, and a language whose .srt could not be downloaded is a note carrying the task id, not a failure. Edit the files, then pass them to dubbing as subtitles so the dub speaks the approved wording; dubbing's subtitle keys must match the languages being dubbed, so leave out the source-language file unless that language is itself a target.

File names come from the prompt (slugified, truncated to 80 characters). When there is no prompt to name a file after — video_to_sfx without one, or an SFX/ducking file recovered via get_sfx_task — the name is sfx-<first 8 chars of the task id> instead. A video_to_music(preserve_speech=true) task recovered via get_sfx_task is named music-<first 8 chars of the task id> instead (get_sfx_task detects the music envelope shape and saves audio/vocals/mux the same way as a direct video_to_music call). Existing files are never overwritten: a -1, -2, … suffix is added instead.

Ducking results are saved as a single file: a .wav, or a .mp4 when the voice input was a video (the ducked mix is muxed back into it). The file name is the voice input's name plus -ducked (e.g. interview.mp4 → interview-ducked.mp4), falling back to ducked-<first 8 chars of the task id> when there is no usable name. A ducking result recovered via get_sfx_task is named sfx-<first 8 chars of the task id> instead, since that tool has no voice file name to work from.

Common Errors

Message

What to do

SONILO_API_KEY not set and no stored credential found

Run sonilo login, or set SONILO_API_KEY in the server's config.

Invalid SONILO_API_KEY

Verify the key at https://platform.sonilo.com/dashboard/api-keys. If you signed in with the CLI, the key may have expired (90 days) or been revoked — run sonilo login again.

Insufficient minutes / Credit limit exceeded

Top up at https://platform.sonilo.com/dashboard/billing.

You've used your N free trial calls for <service>

That service's free trial is spent. Add a payment method at https://platform.sonilo.com/dashboard/billing — retrying can't help. get_account_services shows what is left on the other services.

Rate limit exceeded: your account allows N requests per minute

Calls are going out too fast. The counter runs on a fixed 60-second window and rejected calls count toward it too, so wait the window out instead of retrying inside it. get_account_services reports your rpm_limit; email info@sonilo.com to raise it.

Too many concurrent generations: N of N in progress

Every generation slot is busy. Waiting alone does not free one — a running generation has to finish first. get_account_services reports your concurrency_limit; email info@sonilo.com to raise it.

Generation timed out (music, text_to_music/video_to_music without preserve_speech)

Raise TIME_OUT_SECONDS. Check get_usage to confirm whether the backend completed and charged.

Timed out … waiting for task <id> (SFX, ducking, or video_to_music(preserve_speech=true))

The generation is still running. Call get_sfx_task("<id>") to retrieve the result — nothing is lost, including for a timed-out preserve_speech music task (get_sfx_task recognizes its result shape and saves audio/vocals/mux the same way video_to_music itself would).

Task not found

The task id doesn't exist, or belongs to a purely streaming generation (text_to_music, or video_to_music without preserve_speech), which isn't pollable. Check the id.

Available Tools

16 tools
analyze_videoAnalyze a video for music or sound-effect directionAInspect

Analyze a video and return a CREATIVE BRIEF derived from the footage itself. Generates NOTHING — no audio, no video, no file is written. mode picks which brief comes back: "both" (the default) returns a music-direction brief in segments/variations AND a sound-design brief in sfx_segments/sfx_prompt in one call; "music" returns only the scoring brief (a time-aligned section plan plus one ready-to-use generation prompt per variation); "sfx" returns only the sound-design brief. All three modes cost the same. Use it when the user does not know what music or sound effects the video should get, then feed a variation's prompt into video_to_music, video_to_sfx, video_to_sound or their video-to-video counterparts.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Subject to the account upload cap. video_url (str, optional): HTTP(S) URL to a video file. prompt (str, optional): Guidance for the analysis, e.g. 'focus on the chase'. At most 2000 characters. variants_num (int, optional): 1-5, default 1. How many independent briefs to author for the same video. Billed per brief. mode (str, optional): "both" (default), "music" or "sfx".

Exactly one of video_path and video_url must be provided. Maximum video duration is 480 seconds (8 minutes); billing has a 10-second floor, so a very short clip costs the same as a 10-second one.

Returns: TextContent holding the brief as JSON: mode (echo of the request), segments (start, end, label, prompt) and variations (one prompt each); in both mode also sfx_segments (same shape as segments) and sfx_prompt (a single string, not one per variation). No file path is returned because no file is written. On timeout the error message includes the task_id — recover the brief with get_sfx_task.

Inputs: mode, prompt, video_url, video_path, +1 more. Returns: result

audio_duckingDuck music under voice audioAInspect

Duck a music bed under a voice track: Sonilo lowers the music wherever the voice is speaking and lifts it back in the gaps, then returns the mixed result. The voice input may be a video — its audio track is used as the voice, and the ducked mix is muxed back into a new video.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: voice_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Audio (.wav/.mp3/.m4a/.aac/.ogg/.flac) or video (.mp4/.mov/.avi/.wmv/.webm/.mkv). voice_url (str, optional): HTTPS URL to the voice audio/video. music_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Audio only. music_url (str, optional): HTTPS URL to the music audio. output_directory (str, optional): Where to save the result. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of voice_path/voice_url, and exactly one of music_path/music_url, must be provided. A local file and a URL may be mixed across the two inputs. Each input is capped at 360 seconds (6 minutes) and by the account's upload-size limit (typically 300 MB).

Returns: TextContent with the absolute path of the saved file: a .wav, or a .mp4 when the voice input was a video. If the call times out, the error message includes the task_id — recover the result later with get_sfx_task.

Inputs: music_url, voice_url, music_path, voice_path, +1 more. Returns: result

dubbingDub a video into other languagesAInspect

Dub a video into one or more other languages and save one dubbed video file per language. The speech is translated and re-voiced; the result is a new .mp4 per target language, not an audio track.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges, and you are billed PER LANGUAGE — asking for four languages costs four times as much as one. Free preview: a self-serve account's first call with ONE language and no subtitles is free — the video is trimmed to its first 15 seconds and translated at no charge, and the result carries trial_preview with what the full video would cost. Every call after that, and any call with several languages or subtitles, is billed. Only use when explicitly requested by the user.

This call polls until the backend finishes and waits AT LEAST TWO HOURS before giving up, regardless of any shorter configured timeout — two hours is the backend's own ceiling for the job. A call that sits for an hour or more is normal, not a hang; do not cancel it, since the task keeps running and charging on the backend either way and a cancelled call just loses the caller's easy path to the result.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Supports .mp4/.mov/.webm/.m4v/.gif (gif must be animated). Subject to the account's max upload size (typically 300 MB). Maximum video duration is 300 seconds (5 minutes). video_url (str, optional): HTTPS URL to a video file. Must be https specifically — the dubbing pipeline fetches the source itself and rejects plain http. languages (list, optional): Target language codes, e.g. ["es", "fr"]. Supported: en, zh_cn, ja, ko, pt, pt_br, es, es_419, de, fr, it, ru, th, ar, tr, vi, id, ta, ml, kn, gu, pa_in, sd_in, hi. pt_br is Brazilian Portuguese and es_419 Latin American Spanish; plain pt and es give unqualified Portuguese and Spanish, so pick the regional code when the region matters. ar is likewise unqualified Arabic, not a country dialect. pa_in and sd_in are Punjabi and Sindhi as spoken in India, the only variants available; hi is Hindi. Omit to get the default ["zh_cn", "es", "fr"]. ducking (bool, optional): Duck the background music/effects bed under the dubbed voice while it speaks. Off by default: the bed is always kept, at a constant level unless this is true. Free. lipsync (bool, optional): Whether the speaker's mouth is re-rendered to match the dubbed speech. On by default. Set false to leave the picture completely untouched instead — the video comes back at its original resolution and frame rate rather than re-rendered, and only the audio is replaced, so the mouths keep moving to the original language. Use it for footage with no on-camera speaker, or when preserving the exact original picture matters more than matching lip movement. The background bed is rebuilt either way, so ducking is unaffected. subtitles (dict, optional): One script per target language, e.g. {"es": "/path/es.srt", "fr": "https://example.com/fr.vtt"}. Each value is either a local .srt/.vtt path (absolute, or relative to SONILO_MCP_BASE_PATH) or an https URL. These are TARGET-language scripts carrying the lines to be spoken in that language — not a transcript of the source — and they replace the pipeline's own translation. The keys must match the languages being dubbed exactly; the backend rejects a missing or extra one. export_srt (bool, optional): After the dub, align each language's final audio against its script and also return a re-timed .srt keeping those lines verbatim. Requires subtitles. Off by default. output_directory (str, optional): Where to save the results. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: One TextContent per saved file, named dubbing-<first 8 chars of the task id>..mp4, plus dubbing-<first 8 chars of the task id>..srt when export_srt was used — each reported with that language's export status and alignment loss. A language whose export was blocked still gets its dubbed video and is reported as a note, not a failure. On timeout the error message includes the task_id — recover with get_sfx_task.

Inputs: ducking, lipsync, languages, subtitles, +4 more. Returns: result

get_account_servicesGet Sonilo account servicesA
Read-onlyIdempotent
Inspect

Get the authenticated account's available Sonilo services, rate limits, concurrency limit, discount factor, max video upload size, and — when the account has one — its free-trial allowance. Use this to discover what generation endpoints are available before calling them.

Returns: dict with available_services, rpm_limit, concurrency_limit, discount_factor, max_upload_size_mb, and an optional trial object keyed by service, each {granted, used, remaining}.

Check trial[service]['remaining'] before calling a paid generation tool: at 0 that call fails with 402 trial_exhausted, which no retry fixes — tell the user their free trial for that service is spent and that continuing needs a payment method. The trial key is absent for accounts that have no free-trial allowance; treat that as 'the account bills normally', not as an error. A trial object that IS present but has no entry for the service you're about to call means that service has no free-trial allowance at all — it bills from the first call. dubbing's allowance of 1 is a 15-second PREVIEW, not a full run: the first single-language call translates only the first 15 seconds of the video, free.

Inputs: no named parameters.

get_sfx_taskGet a Sonilo generation task and save its resultAInspect

Check a sound-effects, audio-ducking, video-to-video, dubbing, proofread, or async video-to-music generation task and, if finished, download its result file(s). Use this to recover a result when text_to_sfx, video_to_sfx, audio_ducking, video_to_video_music, video_to_video_sfx, video_to_sound, video_to_video_sound, dubbing, proofread, or video_to_music(preserve_speech=true) timed out — their error message contains the task_id. Does not poll: a single status check per call. This tool itself never charges.

Args: task_id (str): The task id returned in the timeout message. output_directory (str, optional): Where to save result files. Defaults to SONILO_MCP_BASE_PATH.

Returns: Still processing -> a status message; try again later. Succeeded -> the saved file path(s): audio for text_to_sfx and video_to_sfx tasks; a single .wav or .mp4 for audio_ducking tasks; a single .mp4 for video_to_video_music/video_to_video_sfx/video_to_video_sound tasks; a single .wav for video_to_sound tasks; one .mp4 per language for dubbing tasks; one .srt per language, plus the detected source language and cue count, for proofread tasks; for a video_to_music(preserve_speech=true) task, the audio stream(s) plus the preserved speech ('vocals') stem plus the mux (speech+music mixed — the ready-to-use combined result). If the original call used variants_num > 1 (video_to_music, video_to_video_music, video_to_sound, or video_to_video_sound), every variant is saved here too — one file per variant, suffixed -0, -1, .... Failed -> an error including whether the charge was refunded.

Inputs: task_id (required), output_directory. Returns: result

get_usageGet Sonilo usageA
Read-onlyIdempotent
Inspect

Get the authenticated account's usage summary and per-day breakdown. Useful for cost reconciliation and tracking generation history.

Args: days (int, optional): Lookback window in days, 1–365. Defaults to 30.

Inputs: days.

play_audioPlay a local audio fileA
Read-onlyIdempotent
Inspect

Play a local audio file through the system's default output device. Supports WAV, MP3, M4A, AAC, OGG, FLAC.

Args: input_file_path (str): Absolute path or relative to SONILO_MCP_BASE_PATH.

Returns: Success message including the played path.

Inputs: input_file_path (required). Returns: Text content for a message.

proofreadTranscribe and translate a video into editable subtitlesAInspect

Transcribe a video and translate its script into the target dubbing languages, returning one editable .srt per language plus the source-language transcript, so the text can be read and corrected BEFORE anything is dubbed. Nothing is spoken and no video is produced — this is the step before the dubbing tool. Send the edited files back as subtitles on the dubbing tool so the dub speaks exactly the approved wording.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges, and you are billed PER LANGUAGE: video duration × the number of target languages at $0.001/sec, with a 10-second billing floor. A transcript-only request (no languages) counts as one language. Self-serve accounts get 2 free-trial runs on it. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Subject to the account's max upload size (typically 300 MB). video_url (str, optional): HTTPS URL to a video file. Must be https specifically — the backend fetches the source itself and rejects plain http. Either way: Maximum video duration is 300 seconds (5 minutes), and the video must have an audio track. languages (list, optional): Target language codes to translate the transcript into, e.g. ["ja", "zh_cn"]. These are the same codes the dubbing tool takes (see its languages argument for the list), so a proofread script can go straight into a dub. Omit it, or pass an empty list, for the source-language transcript alone. source_language (str, optional): Hint telling transcription which language to expect, one of the same codes — it helps on short, noisy or mixed-language audio. Omit it to have the language detected; either way the result reports the language the transcript is in. output_directory (str, optional): Where to save the results. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: One TextContent per saved file, named proofread-<first 8 chars of the task id>..srt — always including the detected source language as well as every requested target — then the detected source_language and cue_count, then one note per non-blocking warning (e.g. a cue whose text runs too fast to read). A warning never blocks the files. On timeout the error message includes the task_id — recover with get_sfx_task.

Inputs: languages, video_url, video_path, source_language, +1 more. Returns: result

text_to_musicGenerate musicAInspect

Generate music from a text prompt and save the resulting audio file(s) to a local directory. Generated tracks are fully licensed (music licensed via Shutterstock) and cleared for commercial use on social, brand content, and advertising.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: prompt (str): Description of the music to generate (1–1000 chars). duration (int, optional): Length in seconds (5–360). Omit it and Sonilo picks a length that suits the prompt. output_format (str, optional): 'm4a' (default), 'wav', or 'mp3' (320 kbps). Anything but 'm4a' requires the backend's async generation mode (submit + poll) instead of streaming — selected automatically, no user-facing mode param needed. variants_num (int, optional): 1-10, default 1. Generate this many distinct music variants in one request — each is its own creative direction with its own title, not just a re-roll. Cost scales linearly with N. Values above 1 require the backend's async generation mode (handled automatically, same as output_format='wav') and are never covered by the free trial — even a trial account is billed for variants beyond the first. stems (bool, optional): Default false. Pass stems=true to also get the track split into four separate instrument tracks — drums, bass, vocals and other — at no extra charge; it adds a few minutes to the wait (this tool then waits up to 75 minutes), so set it only when the user asks for stems or separated tracks. Uses the backend's async generation mode (handled automatically, same as output_format='wav'). If a stems result comes back with stems_error instead of (or alongside a partial) stems — surfaced here as a note in the returned text — only the separation failed or was skipped: the music itself generated fine, the saved audio files are valid, and the user was not charged for the separation — report it as a missing extra, not as a failed generation. output_directory (str, optional): Absolute path, or relative to SONILO_MCP_BASE_PATH. Defaults to SONILO_MCP_BASE_PATH (~/Desktop unless overridden).

Returns: One TextContent per generated audio stream, each containing the absolute path of the saved audio file (.m4a by default, .wav when output_format='wav'). At variants_num > 1, one entry per variant (suffixed -0, -1, ...), each labeled with its title when the backend provides one. stems=True: also one TextContent per saved stem file (drums/bass/vocals/other, per stream), or a note carrying stems_error when the free separation failed or was skipped.

Inputs: prompt (required), stems, duration, variants_num, +2 more. Returns: result

text_to_sfxGenerate sound effectAInspect

Generate a sound effect from a text prompt and save the audio file to a local directory. Generation is asynchronous on the backend; this tool waits for completion (typically well under the timeout) and returns the saved file path.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: prompt (str): Description of the sound effect (1–2000 chars). duration (float, optional): Length in seconds (0.5–180). Omit it for Sonilo's own default length. audio_format (str, optional): One of wav, mp3, aac, flac. Defaults to aac (.m4a file). output_directory (str, optional): Absolute path, or relative to SONILO_MCP_BASE_PATH. Defaults to SONILO_MCP_BASE_PATH (~/Desktop unless overridden).

Returns: TextContent with the absolute path of the saved audio file. If the call times out, the error message includes the task_id — recover the result later with get_sfx_task.

Inputs: prompt (required), duration, audio_format, output_directory. Returns: result

video_to_musicGenerate music for a videoAInspect

Generate an original score for a video: Sonilo analyzes the video's pacing, motion, and emotion, aligns transitions and beat drops to its cut points, and matches the video's duration exactly. Provide either a local video file path or a publicly accessible video URL. Generated tracks are fully licensed (music licensed via Shutterstock) and cleared for commercial use on social, brand content, and advertising.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Supports .mp4/.mov/.avi/.wmv/.webm/.mkv. Subject to the account's max upload size (typically 300 MB). Maximum video duration is 360 seconds (6 minutes). video_url (str, optional): HTTPS URL to a video file. prompt (str, optional): Style hint for the generated music. preserve_speech (bool, optional): Keep the source speech from the video audible in the result. When set, in addition to the generated music you also get a 'vocals' speech stem and a ready-to-use 'mux' (speech+music, already mixed). Defaults to False. output_format (str, optional): 'm4a' (default), 'wav', or 'mp3' (320 kbps). ducking (bool, optional): Duck the generated music under the source voice at finalize time. Default-OFF server-side: leave unset to skip it, pass True to run it, which adds a ducked track alongside the unchanged clean audio. Free, best-effort. variants_num (int, optional): 1-10, default 1. Generate this many distinct music variants in one request — each is its own creative direction with its own title, not just a re-roll. Cost scales linearly with N. Values above 1 are never covered by the free trial — even a trial account is billed for variants beyond the first. prompt_influence (float, optional): 0-1, API default 0.5. Sets how strongly the generated music follows the prompt; omit it unless the user asks for stricter or looser prompt adherence. Free. stems (bool, optional): Default false. Pass stems=true to also get the generated music split into four separate instrument tracks — drums, bass, vocals and other — at no extra charge; it adds a few minutes to the wait (this tool then waits up to 75 minutes), so set it only when the user asks for stems or separated tracks. It splits the generated music, never the video's own audio. If a stems result comes back with stems_error instead of (or alongside a partial) stems — surfaced here as a note in the returned text — only the separation failed or was skipped: the music itself generated fine, the saved audio files are valid, and the user was not charged for the separation — report it as a missing extra, not as a failed generation. Any of preserve_speech/a non-m4a output_format/ducking/variants_num>1/stems makes this tool internally use the backend's async generation mode (submit + poll) instead of streaming — the call takes longer but the tool still waits for completion. Subject to the same 360-second video duration cap as the plain case. output_directory (str, optional): Where to save the resulting audio file(s). Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: Plain case (no async-triggering param set): one TextContent per generated audio stream, unchanged from before. preserve_speech=True: one TextContent per generated audio stream, plus one for the speech ('vocals') file, plus one per mux stream (speech+music mixed — this is the ready-to-use combined result). ducking=True: also one TextContent per ducked stream (music lowered under the source voice), when the backend rendered one. variants_num > 1: one audio TextContent per variant (suffixed -0, -1, ...), each labeled with its title when the backend provides one. stems=True: also one TextContent per saved stem file (drums/bass/vocals/other, per stream), or a note carrying stems_error when the free separation failed or was skipped. Each TextContent's label says which kind of file it is.

Inputs: stems, prompt, ducking, video_url, +6 more. Returns: result

video_to_sfxGenerate sound effects for a videoAInspect

Generate sound effects for a video: Sonilo analyzes the video and creates matching SFX. Returns the generated sound-effects audio file. Provide either a local video file path or a publicly accessible video URL. Generation is asynchronous on the backend; this tool waits for completion and returns the saved file paths.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Supports .mp4/.mov/.webm/.m4v/.gif (gif must be animated). Subject to the account's max upload size (typically 300 MB). Maximum video duration is 480 seconds (8 minutes). video_url (str, optional): HTTPS URL to a video file. prompt (str, optional): Overall description of the desired sound effects (max 2000 chars). segments (list, optional): Per-segment SFX descriptions, each {"start": float, "end": float, "prompt": str}. Backend rules: first start must be 0; segments must be contiguous (each end == next start); every end > start; every prompt non-empty (max 200 chars); last end must not exceed the video duration; max 30 segments. Invalid segments are rejected before any charge. audio_format (str, optional): One of wav, mp3, aac, flac. Defaults to aac (.m4a file). output_directory (str, optional): Where to save the resulting files. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: One TextContent: the saved audio file path. If the call times out, the error message includes the task_id — recover with get_sfx_task.

Inputs: prompt, segments, video_url, video_path, +2 more. Returns: result

video_to_soundGenerate a full soundtrack for a video (audio output)AInspect

Generate music AND sound effects for a video in one call and return them mixed into a single audio track (no video). Use this instead of calling video_to_music and video_to_sfx separately — the two layers are balanced against each other by the backend, and it is one charge. Provide either a local video path or a public video URL. Generation is asynchronous; this tool waits for completion and returns the saved audio path. Music is fully licensed (via Shutterstock) and cleared for commercial use.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Supports .mp4/.mov/.webm/.m4v/.gif (gif must be animated). Subject to the account's max upload size (typically 300 MB). Maximum video duration is 480 seconds (8 minutes). video_url (str, optional): HTTPS URL to a video file. music_prompt (str, optional): Style hint for the music bed (max 2000 chars). sfx_prompt (str, optional): Description of the sound effects layered over the music (max 2000 chars). segments (list, optional): Per-segment SFX descriptions, each {"start": float, "end": float, "prompt": str}. Backend rules: first start must be 0; segments must be contiguous (each end == next start); every end > start; every prompt non-empty (max 200 chars); last end must not exceed the video duration; max 30 segments. Invalid segments are rejected before any charge. preserve_speech (bool, optional): Keep the speech from the source video in the result. Defaults to False. ducking (bool, optional): Bring the source video's own speech into the mix and dip the generated music under it. Defaults to False, and this endpoint has no keep_original_sound, so by default the result is the generated music and effects ALONE — the source's speech is not in it and there is no music_processed stem. Pass preserve_speech instead to bring in the isolated speech rather than the whole track. output_format (str, optional): Container for the combined track — 'wav' (default), 'm4a', or 'mp3' (320 kbps). Applies to the combined output only; the music and sfx stems keep their native formats. Not available on video_to_video_sound, which always returns an mp4. variants_num (int, optional): 1-10, default 1. Generate this many distinct combined-mix variants in one request. Cost scales linearly with N. Values above 1 are never covered by the free trial — even a trial account is billed for variants beyond the first. output_directory (str, optional): Where to save the result. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: TextContent with the saved .wav path. At variants_num > 1, one TextContent per variant, saved as -0.wav, -1.wav, ... On timeout the error message includes the task_id — recover with get_sfx_task.

Inputs: ducking, segments, video_url, sfx_prompt, +6 more. Returns: result

video_to_video_musicGenerate a music-scored video (video output)AInspect

Generate an original score for a video and return a NEW VIDEO with the music muxed in (not just an audio file). Provide either a local video path or a public video URL. Generation is asynchronous; this tool waits for completion and returns the saved video path. Tracks are fully licensed (via Shutterstock) and cleared for commercial use.

By default the returned video's audio is the generated music ALONE — the source video's own audio is removed. Pass keep_original_sound=True to keep the whole source track with the music statically mixed under it, adding ducking=True to dip the music under the voice instead; or preserve_speech=True to keep only the isolated speech. The source picture is copied without re-encoding, so the input must carry H.264, H.265/HEVC, VP9 or AV1 video in an mp4, mov, m4v or webm container — animated gif and VP8 webm are rejected.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Subject to the account upload cap. Maximum video duration is 360 seconds (6 minutes). video_url (str, optional): HTTPS URL to a video file. prompt (str, optional): Style hint for the generated music. segments (list[dict], optional): How the music should develop over time, as [{"start": float, "prompt": str, "label": str}, ...]. The first start must be 0, starts must be at least 5 seconds apart, and label is one of intro/verse/pre-chorus/chorus/bridge/break/silence/outro/none. Supplying these skips the plan the backend would otherwise derive from prompt. keep_original_sound (bool, optional): Keep the source video's whole original audio track in the result, with the generated music combined under it. Defaults to False, so by default the returned video's audio is the generated music alone. Supersedes preserve_speech. ducking (bool, optional): How the voice and the generated music are COMBINED — not whether a voice is kept. Default False, matching the backend: a static voice-forward mix at a fixed offset. Pass True for the dynamic duck, where the music dips only while the voice is present. Has no effect when there is no voice source, i.e. neither keep_original_sound nor preserve_speech is set. Free and best-effort: silently falls back to generated-audio-only if the source has no usable audio track, voice isolation fails, or the mix fails. preserve_speech (bool, optional): Keep only the source's ISOLATED speech (not the whole track) in the output. Defaults to False. Superseded by keep_original_sound. variants_num (int, optional): 1-10, default 1. Generate this many distinct video variants in one request, each scored with its own creative direction. Cost scales linearly with N. Values above 1 are never covered by the free trial — even a trial account is billed for variants beyond the first. prompt_influence (float, optional): 0-1, API default 0.5. Sets how strongly the generated music follows the prompt; omit it unless the user asks for stricter or looser prompt adherence. Free. output_directory (str, optional): Where to save the result. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: TextContent with the saved .mp4 path. At variants_num > 1, one TextContent per variant, saved as -0.mp4, -1.mp4, ... On timeout the error message includes the task_id — recover with get_sfx_task.

Inputs: prompt, ducking, segments, video_url, +6 more. Returns: result

video_to_video_sfxGenerate a sound-effects video (video output)AInspect

Generate sound effects for a video and return a NEW VIDEO with the SFX muxed in (not just an audio file). Provide either a local video path or a public video URL. Generation is asynchronous; this tool waits for completion and returns the saved video path.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Supports .mp4/.mov/.webm/.m4v/.gif (gif must be animated). Subject to the account's max upload size (typically 300 MB). Maximum video duration is 480 seconds (8 minutes). video_url (str, optional): HTTPS URL to a video file. prompt (str, optional): Overall description of the desired sound effects (max 2000 chars). segments (list, optional): Per-segment SFX descriptions, each {"start": float, "end": float, "prompt": str}. Backend rules: first start must be 0; segments must be contiguous (each end == next start); every end > start; every prompt non-empty (max 200 chars); last end must not exceed the video duration; max 30 segments. Invalid segments are rejected before any charge. output_directory (str, optional): Where to save the result. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: TextContent with the saved .mp4 path. On timeout the error message includes the task_id — recover with get_sfx_task.

Inputs: prompt, segments, video_url, video_path, +1 more. Returns: result

video_to_video_soundGenerate a fully-scored video (video output)AInspect

Generate music AND sound effects for a video in one call and return a NEW VIDEO with the mixed soundtrack muxed in (not just an audio file). Use this instead of chaining video_to_video_music and video_to_video_sfx — the two layers are balanced against each other by the backend, and it is one charge. Provide either a local video path or a public video URL. Generation is asynchronous; this tool waits for completion and returns the saved video path. Music is fully licensed (via Shutterstock) and cleared for commercial use.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: video_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Supports .mp4/.mov/.webm/.m4v/.gif (gif must be animated). Subject to the account's max upload size (typically 300 MB). Maximum video duration is 480 seconds (8 minutes). video_url (str, optional): HTTPS URL to a video file. music_prompt (str, optional): Style hint for the music bed (max 2000 chars). sfx_prompt (str, optional): Description of the sound effects layered over the music (max 2000 chars). segments (list, optional): Per-segment SFX descriptions, each {"start": float, "end": float, "prompt": str}. Backend rules: first start must be 0; segments must be contiguous (each end == next start); every end > start; every prompt non-empty (max 200 chars); last end must not exceed the video duration; max 30 segments. Invalid segments are rejected before any charge. keep_original_sound (bool, optional): Keep the source video's whole original audio track in the result, with the generated music and effects combined under it. Defaults to False, so by default the returned video's audio is the generated music and effects ALONE and the source's own audio is removed — and the result carries no music_processed stem, since with no voice source there is no processed track. Supersedes preserve_speech. preserve_speech (bool, optional): Keep only the source's ISOLATED speech (not the whole track) in the result. Defaults to False. Superseded by keep_original_sound. ducking (bool, optional): How the voice and the generated bed are COMBINED — not whether a voice is kept. Defaults to False: a static voice-forward mix at a fixed offset. Pass True for the dynamic duck, where the bed dips only while the voice is present. Has no effect when there is no voice source, i.e. neither keep_original_sound nor preserve_speech is set. variants_num (int, optional): 1-10, default 1. Generate this many distinct combined-mix variants in one request. Cost scales linearly with N. Values above 1 are never covered by the free trial — even a trial account is billed for variants beyond the first. output_directory (str, optional): Where to save the result. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of video_path and video_url must be provided.

Returns: TextContent with the saved .mp4 path. At variants_num > 1, one TextContent per variant, saved as -0.mp4, -1.mp4, ... On timeout the error message includes the task_id — recover with get_sfx_task.

Inputs: ducking, segments, video_url, sfx_prompt, +6 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 16 tools

    Disambiguation3/5

    The set includes parallel variants such as video_to_music vs video_to_video_music, video_to_sfx vs video_to_video_sfx, and especially video_to_sound vs video_to_video_sound, which differ only by output type and are easy to misselect. The descriptions do clarify the audio-vs-video distinction and when to use the combined tools, but the boundaries are not immediately obvious from names alone.

    Naming Consistency4/5

    Almost all tools use snake_case with an action-oriented pattern, and the video_to_* versus video_to_video_* convention is mostly systematic. Minor deviations such as dubbing and proofread, which are not verb_noun names, prevent a perfect score.

    Tool Count4/5

    At 16 tools this is slightly above the ideal range, but each tool maps to a distinct generation mode or administrative function. The six video-music/SFX variants are numerous but justified by different outputs and cost-saving combined operations.

    Completeness4/5

    The surface covers text and video music/SFX generation, combined music+SFX, dubbing, proofreading, creative analysis, account/usage inspection, task recovery, and audio playback. Minor gaps remain, such as listing or cancelling in-flight tasks and no equivalent video playback or task-management browser.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers