video-to-music

Sonilo 视频转音乐

把一段已完成的视频交给 Sonilo，它会为剪辑创作原创配乐——匹配节奏、动作和情绪，让转场和节拍落点与剪辑对齐，时长与视频完全一致。这是 Sonilo 的旗舰功能。所有曲目均已获授权（音乐通过 Shutterstock 授权），可用于社交媒体、品牌内容和广告等商业用途。

**设置：**请参阅 setup-api-key 技能，连接 Sonilo MCP 服务并进行身份验证——使用 sonilo login（无需密钥）或 SONILO_API_KEY。

⚠️ **费用：**以下每种工具都会调用 API，可能产生费用。只有在用户确实要求生成内容时才调用。如果不确定免费试用次数是否还有剩余，请查看 get_account_services（参阅 account 技能）。

传输方式：MCP 或 CLI

在会话开始时选择一种方式，并在整个会话中保持一致。不要在同一任务中混用，也不要宣布所选方式。

1. 本会话中可见 Sonilo MCP 工具（video_to_music 等）——请使用这些工具。这是首选方式：无需 shell，而且只有这种方式能适用于耗时很长的生成任务。如果调用因身份验证失败（而不是输入参数错误）而失败，则此会话无法使用这种传输方式：请改用第 2 种方式，不要重试。
2. 没有可用的 Sonilo MCP 工具，但 sonilo account 退出码为 0——请使用下方的 CLI 命令。API、账户和凭据文件都相同。请用 sonilo account 进行探测，不要用 sonilo whoami：即使已退出登录，whoami 也会以 0 退出，因此无法区分这两种状态。
3. 两种方式都不可用——请停止并运行 setup-api-key 技能。不要用 curl 调用 api.sonilo.com 作为变通方法；两种传输方式都会处理上传、轮询和重试，而直接请求无法做到这些。

快速开始

MCP 工具调用（推荐）

video_to_music(
    video_path="~/Desktop/trailer.mp4",
    prompt="Build suspense, then resolve with a warm cinematic finish"
)

生成的文件会保存到 SONILO_MCP_BASE_PATH（默认为 ~/Desktop），并以文本形式返回保存路径。

Python（pip install sonilo）

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

score = client.video_to_music.generate(video="trailer.mp4", prompt="Build suspense, then resolve with a warm cinematic finish")
score.save("score.m4a")

# video_to_video_music: get the video back with the music muxed in
video = client.video_to_video_music.generate(video="trailer.mp4", prompt="cinematic, uplifting")
video.save("scored.mp4")

在 video_to_music 中使用 preserve_speech=True 需要异步方式——请使用 generate_async() 而不是 generate()，以获取额外的 vocals/mux/ducked 输出；完整用法请参阅 sonilo-python 的 README。

JavaScript / TypeScript（npm install sonilo）

import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const score = await client.videoToMusic.generate({
  video: "./trailer.mp4",
  prompt: "Build suspense, then resolve with a warm cinematic finish",
});

// video_to_video_music: get the video back with the music muxed in
const video = await client.videoToVideoMusic.generate({
  video: "./trailer.mp4",
  prompt: "cinematic, uplifting",
});

在 videoToMusic 中使用 preserveSpeech: true 需要异步方式——请使用 .submit() + client.tasks.wait() 而不是 .generate()；完整用法请参阅 sonilo-js 的 README。

CLI（npm install -g sonilo-cli 或 pip install sonilo-cli）

sonilo video-to-music --video trailer.mp4 --prompt "Build suspense, then resolve with a warm cinematic finish" --output score.m4a

--format wav、--preserve-speech 和 --isolate-vocals 都会让 video-to-music 改用异步提交并轮询的方式。

# the muxed video, from the CLI
sonilo video-to-video-music --video trailer.mp4 --prompt "cinematic, uplifting" --output scored.mp4

cURL（原始 REST API，无 MCP 主机）

curl -X POST "https://api.sonilo.com/v1/video-to-music" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Build suspense, then resolve with a warm cinematic finish" \
  --output score.m4a

video_to_music 也接受 video_url 表单字段，可替代上传文件——二者任选其一，不能同时提供。

工具

工具	描述
video_to_music(video_path? | video_url?, prompt?, preserve_speech?, output_format?, ducking?, variants_num?, prompt_influence?, stems?, output_directory?)	为视频配乐：匹配节奏、动作和情绪，时长与视频完全一致。仅返回音频（不会将视频本身与音频合并）。
video_to_video_music(video_path? | video_url?, prompt?, segments?, keep_original_sound?, ducking?, preserve_speech?, variants_num?, prompt_influence?, output_directory?)	配乐方式相同，但会返回一个已合并音乐的新 .mp4。默认会丢弃源视频自带的音频——请参阅 keep_original_sound。

参数

参数	类型	默认值	备注
prompt	string	—	可选的风格提示。省略此项可让画面内容完全主导。
video_path	string	—	绝对路径，或相对于 SONILO_MCP_BASE_PATH 的路径。支持 .mp4/.mov/.avi/.wmv/.webm/.mkv。最长 360s（6 min），且受账户上传大小上限约束（通常为 300 MB）。
video_url	string	—	视频文件的 HTTPS URL。video_path/video_url 必须且只能指定一项。
preserve_speech	bool	false	保留可听见的原始语音。在 video_to_music 中，还会返回 vocals 语音分轨和可直接使用的 mux（语音与音乐混音）——这会让调用改为异步运行（提交 + 轮询），而不是流式传输，因此耗时稍长，但工具仍会等待任务完成。
ducking	bool | null	video_to_music 默认为 ON，video_to_video_music 默认为 false	降低生成音乐的音量，使其弱于原始人声。免费，尽力而为。在 video_to_video_music 中，此参数只有与 keep_original_sound 或 preserve_speech 一起使用才会生效——若两者都未设置，输出中便没有可供音乐避让的原始人声。
keep_original_sound	bool	false	仅适用于 video_to_video_music。**结果听起来不对时，应使用此参数。**默认情况下，返回的 .mp4 只包含生成的音乐——原始对话、环境音和音效都会被移除。设为 true 可保留完整的原始音轨，并将音乐混入其中；再添加 ducking=true，可降低音乐音量以避让人声，而不是平铺混音。keep_original_sound 优先于 preserve_speech。
variants_num	int	1	1–10。一次请求生成多个不同的创意方向——这些是不同版本，而不是同一版本的重新渲染。费用随数量线性增长，且任何大于 1 的值都不在免费试用范围内，因此请先与用户确认数量。大于 1 时，每个变体都会写入一个文件，并强制使用后端的异步模式。
prompt_influence	float | null	API 默认值 0.5	0–1：控制音乐遵循提示词的严格程度，相对于视频本身所传达的内容而言。数值较低时由画面主导，较高时则更严格地遵循要求。免费，且不会改变运行模式或文件数量——除非用户要求提高或降低遵循程度，否则请省略此项。
stems	bool	false	仅适用于 video_to_music——video_to_video_music 没有此参数。免费。此外，每条生成的音轨都会被拆分为四条独立的乐器分轨——drums、bass、vocals、other——并与未经处理的完整混音一同返回。此参数不会处理视频自身的音频。在 REST 中仅支持异步模式（未设置 mode=async 时，stems=true 会返回 400）。参见分轨。
output_format	string	m4a	仅适用于 video_to_music——video_to_video_music 没有此参数，且始终输出混音后的 .mp4。支持 m4a 或 wav。wav（以及 preserve_speech/ducking）会在内部触发后端的异步模式。
output_directory	string	SONILO_MCP_BASE_PATH	绝对路径，或相对于基础路径的路径。

分轨

在 video_to_music 中设置 stems=true，还会免费返回每首生成曲目拆分成的四条独立乐器音轨——drums、bass、vocals、other。完整混音不会受到影响；分轨会与混音一同出现在任务结果中，作为与 audio 并列的 stems 数组：

"stems": [
  {
    "stream_index": 0,
    "drums":  { "url": "…", "content_type": "audio/mp4", "file_size": 2913044 },
    "bass":   { "url": "…", "content_type": "audio/mp4", "file_size": 2870211 },
    "vocals": { "url": "…", "content_type": "audio/mp4", "file_size": 2794560 },
    "other":  { "url": "…", "content_type": "audio/mp4", "file_size": 3011830 }
  }
]

使用时需要注意：

• 它拆分的是生成的音乐，而不是视频本身的音频。 vocals 分轨包含生成配乐中的演唱内容——配乐通常以纯器乐为主，因此这一分轨通常几乎无声。这是正常现象，并非错误。若要分离源音频中的语音，请改用 preserve_speech（另一项功能）。
• REST 仅支持异步模式。 stems=true 必须搭配 mode=async（否则返回 400）：你会获得 202 和 task_id，然后轮询 /v1/tasks/{task_id}。MCP 工具始终采用异步模式，因此在托管服务上可直接使用该参数。
• 所有接口均可使用（已于 2026-08-17 验证）：REST、托管 MCP 服务、本地 sonilo-mcp 软件包（>= 0.18.0）、SDK（sonilo npm >= 0.16.0，PyPI >= 0.15.0），以及 CLI（--stems，npm sonilo-cli >= 0.15.0，PyPI sonilo-cli >= 0.14.0）。
• 使用 stream_index 将分轨与曲目对应，切勿依赖数组位置。 分离失败的流不会出现在数组中，因此 stems 可能比 audio 短。
• stems_error 不代表生成失败。 若分离全部或部分失败，或被跳过，任务会携带一条 stems_error 字符串；此时也可能同时有部分 stems 数组。生成本身已成功，且每个 audio URL 均有效：应将缺失的分轨视为缺少附加内容，绝不要因此重试或申请退款。
• **耗时：**分离在生成完成后进行，通常还需 2–6 min，30 min 后放弃（随后会出现 stems_error）。
• 四种分轨名称固定（采用 htdemucs 分离）：钢琴、合成器、吉他、弦乐等旋律乐器会归入 other。
• **格式：**分轨通常遵循 output_format；实际交付格式请以每条分轨的 content_type 为准。

提示词

无需提示词——模型会读取视频剪辑。简短、有条理的说明可以补充视频无法传达的信息：你的意图、流派、必须突出呈现的时刻，以及绝不能出现的声音。

付费调用前：确认视频的准确时长和现有音频，遵守 360 s 上限（超出会被 422 拒绝，不会截断），并取得确认——失败的运行会自动退款，但你自行重试会产生新的费用。先写好说明，生成一次，再迭代提示词，而不是反复重生成。

• 完整的调用前检查（检查视频、上限、额度、验证）：references/preflight.md
• 风格提示词撰写（音频说明、流派／能量措辞、preserve_speech、分段音乐）：references/music-prompting.md

工作流提示

• **提示词：**风格提示（例如“电影感、振奋人心”）会引导生成结果，但提示词是可选的——Sonilo 已经会读取视频素材。
• **对口播或旁白视频使用 preserve_speech：**如果源视频中有用户希望保留的对白或画外音，请设置 preserve_speech=true。不同工具的行为有所不同：使用 video_to_music 时，会得到音乐、分离出的人声轨，以及已混音的合成文件（mux）——请直接使用 mux，而不要自行重新混音。使用 video_to_video_music 时，不会提供单独的人声轨或 mux 文件；它只会在单个混流输出视频中保留源视频中可听见的人声。
• **想要获得已加入配乐的视频？**请使用 video_to_video_music，而不是 video_to_music——输入相同，但输出是新的 .mp4，而不只是音频。请提醒用户：默认会丢弃源音频：如果用户希望听到视频中的对白、旁白或音效，请传入 keep_original_sound=true（添加 ducking=true 可让人声保持在前景），或者传入 preserve_speech=true，仅保留分离出的人声。遇到“音乐有了，但我的旁白不见了”这类反馈，原因一定是这个。
• 一次生成多个版本：variants_num=3 会针对一个请求生成三个不同方向的版本，而不是重新生成三次。费用是 3 倍，且绝不包含在免费试用额度内——调用前请说明价格。
• 用户想把配乐中的乐器分别导出为文件（以便重新混音、调整平衡或移除某种乐器）？在 video_to_music 中设置 stems=true——此功能免费，但仅支持异步处理，且尚未在所有界面推出；它会拆分生成的音乐，而不是源音频；请参阅 分轨。
• **时长：**始终自动匹配源视频——无需询问。
• 还需要音效？若要在一次均衡且仅收费一次的调用中，为同一视频生成音乐和音效，请使用 video-to-sound，而不是分别调用此工具和 video-to-sfx。
• **不知道应该是什么声音？**请先运行 video-analysis：一次调用即可返回分段方案，以及根据视频素材提取的可直接使用的生成提示词（除非传入 mode="music"，否则还会提供声音设计概要），比猜提示词再反复生成更有效。这是一次付费调用，但不会生成任何内容，因此只有在需求确实不明确时才使用——用户已经说明想要什么时就不必使用。
• **内容限制：**提示词不得提及具体艺人、乐队或受版权保护的歌词。

恢复超时调用

video_to_music（未使用 preserve_speech/ducking/stems/output_format="wav" 中的任何参数）会在一次调用中流式返回结果。任何会触发后端异步模式的变体，以及始终采用异步模式的 video_to_video_music，都可能在 TIME_OUT_SECONDS 设得很长时发生超时。如果发生超时，错误消息会包含一个 task_id；生成任务会继续在后端运行（且费用已产生）。调用 get_sfx_task(task_id)——在托管服务上则调用 get_generation_task(task_id)——即可在结果就绪后获取；请参阅 task-recovery 技能。

输出文件

• video_to_music：默认输出 .m4a（如有请求则输出 .wav），文件名取自提示词（转换为 slug 格式），或为 sonilo-<timestamp>.m4a。多个并行流的文件名会添加 -<index> 后缀。
• video_to_music(preserve_speech=true)：还会保存 <base>-vocals.<ext>（分离出的人声）和 <base>-mux.<ext>（人声与音乐合并后的文件——实际应使用这个文件）。
• video_to_video_music：输出单个加入配乐的 .mp4。

错误处理

常见错误：401 密钥无效，402 余额不足／试用额度已用尽，413 文件过大，422 参数无效（例如视频超过 360 s 上限），429 请求频率超限。调用前请参阅 account 技能，检查试用额度／使用情况；具体的恢复步骤请参阅 sonilo-mcp README 中的错误表。