0.22.0pypi · sonilo-mcp · latest release
Observed 2026-09-05T13:34:07.688Z using mcpSecurity-inventory. Protocol 2025-06-18.
| Tool | Category | Risk |
|---|---|---|
analyze_videoAnalyze a video and return a CREATIVE BRIEF for scoring it: a time-aligned section plan plus one ready-to-use generation prompt per variation, derived from the footage itself. Generates NOTHING — no audio, no video, no file is written. 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.
Exactly one of video_path and video_url must be provided. Maximum video duration is 360 seconds (6 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: `segments` (start, end, label, prompt) and `variations` (one prompt each). 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.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt"
},
"variants_num": {
"default": 1,
"title": "Variants Num",
"type": "integer"
}
},
"title": "analyze_videoArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "analyze_videoOutput",
"type": "object"
} | — | — |
audio_duckingDuck 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.Input schema{
"properties": {
"voice_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Voice Path"
},
"voice_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Voice Url"
},
"music_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Music Path"
},
"music_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Music Url"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "audio_duckingArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "audio_duckingOutput",
"type": "object"
} | — | — |
dubbingDub 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. This tool has ZERO free-trial runs — even a trial account is billed from the first call. 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. 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. 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.
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>.<language>.mp4. On timeout the error message includes the task_id — recover with get_sfx_task.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"languages": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Languages"
},
"ducking": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Ducking"
},
"lipsync": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Lipsync"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "dubbingArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "dubbingOutput",
"type": "object"
} | — | — |
get_account_servicesGet 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 (this is dubbing's situation on any self-serve trial account).Input schema{
"properties": {},
"title": "get_account_servicesArguments",
"type": "object"
} | — | — |
get_sfx_taskCheck a sound-effects, audio-ducking, video-to-video, dubbing, 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, 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; 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.Input schema{
"properties": {
"task_id": {
"title": "Task Id",
"type": "string"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"required": [
"task_id"
],
"title": "get_sfx_taskArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "get_sfx_taskOutput",
"type": "object"
} | — | — |
get_usageGet 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.Input schema{
"properties": {
"days": {
"default": 30,
"title": "Days",
"type": "integer"
}
},
"title": "get_usageArguments",
"type": "object"
} | — | — |
play_audioPlay 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.Input schema{
"properties": {
"input_file_path": {
"title": "Input File Path",
"type": "string"
}
},
"required": [
"input_file_path"
],
"title": "play_audioArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
}
},
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
} | — | — |
text_to_musicGenerate 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): Length in seconds (1–360).
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 40 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.Input schema{
"properties": {
"prompt": {
"title": "Prompt",
"type": "string"
},
"duration": {
"title": "Duration",
"type": "integer"
},
"output_format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Format"
},
"variants_num": {
"default": 1,
"title": "Variants Num",
"type": "integer"
},
"stems": {
"default": false,
"title": "Stems",
"type": "boolean"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"required": [
"prompt",
"duration"
],
"title": "text_to_musicArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "text_to_musicOutput",
"type": "object"
} | — | — |
text_to_sfxGenerate 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 (int): Length in seconds (1–180).
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.Input schema{
"properties": {
"prompt": {
"title": "Prompt",
"type": "string"
},
"duration": {
"title": "Duration",
"type": "integer"
},
"audio_format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Audio Format"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"required": [
"prompt",
"duration"
],
"title": "text_to_sfxArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "text_to_sfxOutput",
"type": "object"
} | — | — |
video_to_musicGenerate 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 40 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.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt"
},
"preserve_speech": {
"default": false,
"title": "Preserve Speech",
"type": "boolean"
},
"output_format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Format"
},
"ducking": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Ducking"
},
"variants_num": {
"default": 1,
"title": "Variants Num",
"type": "integer"
},
"prompt_influence": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt Influence"
},
"stems": {
"default": false,
"title": "Stems",
"type": "boolean"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "video_to_musicArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "video_to_musicOutput",
"type": "object"
} | — | — |
video_to_sfxGenerate 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.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt"
},
"segments": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Segments"
},
"audio_format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Audio Format"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "video_to_sfxArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "video_to_sfxOutput",
"type": "object"
} | — | — |
video_to_soundGenerate 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 <base>-0.wav, <base>-1.wav, ... On timeout the error message includes the task_id — recover with get_sfx_task.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"music_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Music Prompt"
},
"sfx_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Sfx Prompt"
},
"segments": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Segments"
},
"preserve_speech": {
"default": false,
"title": "Preserve Speech",
"type": "boolean"
},
"ducking": {
"default": false,
"title": "Ducking",
"type": "boolean"
},
"output_format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Format"
},
"variants_num": {
"default": 1,
"title": "Variants Num",
"type": "integer"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "video_to_soundArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "video_to_soundOutput",
"type": "object"
} | — | — |
video_to_video_musicGenerate 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 <base>-0.mp4, <base>-1.mp4, ... On timeout the error message includes the task_id — recover with get_sfx_task.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt"
},
"segments": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Segments"
},
"keep_original_sound": {
"default": false,
"title": "Keep Original Sound",
"type": "boolean"
},
"ducking": {
"default": false,
"title": "Ducking",
"type": "boolean"
},
"preserve_speech": {
"default": false,
"title": "Preserve Speech",
"type": "boolean"
},
"variants_num": {
"default": 1,
"title": "Variants Num",
"type": "integer"
},
"prompt_influence": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt Influence"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "video_to_video_musicArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "video_to_video_musicOutput",
"type": "object"
} | — | — |
video_to_video_sfxGenerate 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.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt"
},
"segments": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Segments"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "video_to_video_sfxArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "video_to_video_sfxOutput",
"type": "object"
} | — | — |
video_to_video_soundGenerate 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 <base>-0.mp4, <base>-1.mp4, ... On timeout the error message includes the task_id — recover with get_sfx_task.Input schema{
"properties": {
"video_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Path"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Video Url"
},
"music_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Music Prompt"
},
"sfx_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Sfx Prompt"
},
"segments": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Segments"
},
"keep_original_sound": {
"default": false,
"title": "Keep Original Sound",
"type": "boolean"
},
"preserve_speech": {
"default": false,
"title": "Preserve Speech",
"type": "boolean"
},
"ducking": {
"default": false,
"title": "Ducking",
"type": "boolean"
},
"variants_num": {
"default": 1,
"title": "Variants Num",
"type": "integer"
},
"output_directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Output Directory"
}
},
"title": "video_to_video_soundArguments",
"type": "object"
}Output schema{
"$defs": {
"Annotations": {
"additionalProperties": true,
"properties": {
"audience": {
"anyOf": [
{
"items": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Audience"
},
"priority": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
}
},
"title": "Annotations",
"type": "object"
},
"TextContent": {
"additionalProperties": true,
"description": "Text content for a message.",
"properties": {
"type": {
"const": "text",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"annotations": {
"anyOf": [
{
"$ref": "#/$defs/Annotations"
},
{
"type": "null"
}
],
"default": null
},
"_meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Meta"
}
},
"required": [
"type",
"text"
],
"title": "TextContent",
"type": "object"
}
},
"properties": {
"result": {
"items": {
"$ref": "#/$defs/TextContent"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"title": "video_to_video_soundOutput",
"type": "object"
} | — | — |
Compared with initial baseline using full_baseline.
| Risk | Change | Subject |
|---|---|---|
| No material changes recorded. | ||
| Severity | Finding | Advisory |
|---|---|---|
| No confirmed vulnerability is published for this version. | ||
Artifact SHA-256: 14bac0fa1515f356e1ab77a0eaaf15814972c38aebffc73c14c188681ffc8973
Scanner: mcp-proof-engine 0.1.0.