Sonilo MCP

Official

Overview Schema Source Related Servers Discussions Admin

Generate a music-scored video (video output)

video_to_video_music

Generate an original licensed score for a video and return a new video with the music mixed in, not just an audio file. Provide a local path or URL; the source video's audio is removed by default.

Instructions

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.

Input Schema

Name	Required	Description	Default
`prompt`	No
`ducking`	No
`segments`	No
`video_url`	No
`video_path`	No
`variants_num`	No
`preserve_speech`	No
`output_directory`	No
`prompt_influence`	No
`keep_original_sound`	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 declare the write/open-world profile; the description adds the substantive behavior: asynchronous execution that blocks until done, no re-encoding of the source picture with an accepted codec/container list, the default of discarding source audio, ducking's silent best-effort fallback, and that variants above 1 are billed even on trial. This is well beyond what the annotations convey.

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 the distinguishing output type and the cost gate, then a well-structured Args block. It is long, and the 'music ALONE' default is stated twice (prose and keep_original_sound), but the length is largely justified by ten undocumented-in-schema parameters.

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 paid, async, ten-parameter mutation tool with an output schema, nothing material is missing: input constraints, format rejection rules, mode interactions, cost behavior, and return shape (including variant naming and timeout recovery) are all covered.

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%, so the description carries the full burden and does: it documents all ten parameters including segment structure rules (first start 0, ≥5s apart, label enum values), ducking's precise meaning and no-op conditions, supersede relationships between keep_original_sound/preserve_speech, variant cost scaling, and prompt_influence's 'leave it alone' default.

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 an original score for a video and return a NEW VIDEO with the music muxed in') and explicitly distinguishes itself from the audio-only sibling by parenthesizing 'not just an audio file'. An agent can pick it apart from video_to_music / video_to_video_sound without opening a schema.

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?

Gives explicit when-to-use guidance ('Only use when explicitly requested by the user' due to cost), the exact-one-of constraint on video_path vs video_url, and a decision path for the audio modes (default alone, keep_original_sound, +ducking, or preserve_speech). It also names the recovery route via get_sfx_task on timeout.

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

Deploy Server