Sonilo MCP

Official

Overview Schema Source Related Servers Discussions Admin

Generate a full soundtrack for a video (audio output)

video_to_sound

Generate balanced music and sound effects for a video in one call, returning them mixed into a single audio track without the video.

Instructions

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.

Input Schema

Name	Required	Description	Default
`ducking`	No
`segments`	No
`video_url`	No
`sfx_prompt`	No
`video_path`	No
`music_prompt`	No
`variants_num`	No
`output_format`	No
`preserve_speech`	No
`output_directory`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.28.0Oct 29, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only convey readOnly=false and openWorld=true; the description supplies the operationally important facts an agent cannot infer: asynchronous with a blocking wait, per-call charge, validation happens before any charge, licensing/clearance, linear cost scaling with variants_num, variants >1 never trial-covered, and timeout recovery via get_sfx_task. It also discloses a default-state trap (ducking has no keep_original_sound, so the result excludes source speech by default).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling-routing decision, then cost warning, then parameters. Nearly every clause carries unique information, but the density is high — the ducking/preserve_speech explanation and the output_format comparison to video_to_video_sound repeat context. Given 0% schema coverage this length is largely justified rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, asynchronous, billable, file-writing tool this covers everything an agent needs: input formats and limits, validation-before-charge, cost model including the trial carve-out, variant naming, and failure recovery. Output-schema existence notwithstanding, it still explains the variant file naming and the timeout error's task_id, which are behavioral rather than structural.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 10 parameters, so full burden is on the description — and it delivers for nearly every one: accepted formats and 300 MB / 480 s limits for video_path, max 2000 chars for both prompts, max 200 chars and six backend contiguity rules for segments, defaults and semantics for preserve_speech/ducking, allowed enum-ish values and stem caveat for output_format, range and billing behavior for variants_num, and the default base path for output_directory. It also adds the cross-parameter constraint the schema omits ("Exactly one of video_path and video_url").

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Generate music AND sound effects for a video") plus the output shape ("mixed into a single audio track (no video)"), which immediately distinguishes it from video_to_music/video_to_sfx (separate layers) and video_to_video_sound (returns mp4). The parenthetical "(no video)" resolves the one ambiguity an agent would have against its sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: "Use this instead of calling video_to_music and video_to_sfx separately" with the reasons (backend balance, single charge). It also states the gating condition "Only use when explicitly requested by the user" and gives a redirect for a related need ("Pass preserve_speech instead to bring in the isolated speech"), so both when-to-use and when-not are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server