audio-ducking

Sonilo 音频闪避

自动降低人声轨道下方的背景音乐音量：人声说话时，Sonilo 会降低音乐音量，并在停顿时将其调高，然后返回混音结果。人声输入也可以是视频——系统会将其音轨用作人声，并将闪避后的混音复用到新视频中。

设置： 请参阅 setup-api-key 技能。

⚠️ 费用： 此操作会发起可能产生费用的 API 调用。仅在明确请求时调用。

传输方式：MCP 或 CLI

在会话开始时选择一种方式，并始终使用该方式。请勿在同一任务中混用两种方式，也不要说明所选方式。

1. 本会话中可见 Sonilo MCP 工具（audio_ducking 等）——请使用这些工具。这是首选方式：无需 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 工具调用（推荐）

audio_ducking(
    voice_path="~/Desktop/interview.mp4",
    music_path="~/Desktop/background-track.wav"
)

Python（pip install "sonilo>=0.13"）

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

result = client.audio_ducking.generate(
    voice="interview.mp4",  # audio or video; also voice_url=
    music="background-track.wav",  # audio only; also music_url=
)
result.save("ducked.mp4" if result.output_type == "video" else "ducked.wav")

JavaScript / TypeScript（npm install sonilo@>=0.14）

import { SoniloClient, download } from "sonilo";
import { writeFile } from "node:fs/promises";

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

const result = await client.audioDucking.generate({
  voice: "./interview.mp4", // audio or video; also voiceUrl
  musicUrl: "https://example.com/background-track.wav", // audio only; also music
});
await writeFile(
  result.output_type === "video" ? "ducked.mp4" : "ducked.wav",
  await download(result.output_url!),
);

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

sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/background-track.wav

底层始终采用异步处理——CLI 会为你提交任务并进行轮询。--voice/--voice-url 必须且只能指定一个，--music/--music-url 也必须且只能指定一个。默认输出名称取决于返回内容（output.wav，或者人声输入为视频时的 output.mp4）；可通过 --output 覆盖。本地 --music 文件必须具有音频扩展名——CLI 会提前拒绝视频文件，原因与 MCP 工具相同。

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

curl -X POST "https://api.sonilo.com/v1/audio-ducking" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"
# -> {"task_id": "..."}  poll GET /v1/tasks/{task_id}

本地文件使用 voice_file/music_file 多部分字段；远程来源则使用 voice_url/music_url 表单字段（两个输入可以自由混用）。

工具

工具	说明
audio_ducking(voice_path? | voice_url?, music_path? | music_url?, output_directory?)	在 voice 下方混入 music，并在人声说话时自动降低音乐音量。

参数

参数	类型	说明
voice_path	字符串	绝对路径，或相对于 SONILO_MCP_BASE_PATH 的路径。音频或视频：.wav/.mp3/.m4a/.aac/.ogg/.flac 或 .mp4/.mov/.avi/.wmv/.webm/.mkv。
voice_url	字符串	人声音频/视频的 HTTPS URL。voice_path/voice_url 必须且只能指定一个。
music_path	字符串	绝对路径，或相对于基础路径的路径。仅限音频——视频在此处不会被特殊处理，可能会导致错误处理。
music_url	字符串	背景音乐的 HTTPS URL。music_path/music_url 必须且只能指定一个。
output_directory	字符串	默认为 SONILO_MCP_BASE_PATH。

每个输入的时长上限为 360 秒（6 分钟），且还受账户上传大小限制（通常为 300 MB）。

工作流提示

• 此工具需要两个已存在的音轨——它本身不会生成音乐或音效。如果需要先生成背景音乐，请使用 text-to-music 或 video-to-music 技能（text_to_music/video_to_music），然后将结果作为 music_path 传入此处。
• 语音输入可以是视频。 如果用户提供了一段人物访谈视频或采访视频，以及一个单独的音乐文件，请直接将视频作为 voice_path 传入——Sonilo 会提取视频中的音轨，将音乐音量压低至语音之下，并自动将压低后的混音重新封装到新视频中。
• 如果音乐本身也是为同一视频生成的，优先使用 video-to-sound 或 video_to_music(ducking=true)——这些工具会在生成过程中内部压低音乐音量，因此无需单独调用压低工具。只有当音乐音轨是固定的或来自外部、而你只需要混音时，才使用 audio_ducking。

恢复超时的调用

此工具会在后端提交一个异步任务。如果调用超时，错误信息中会包含 task_id——任务仍会继续运行（且已计费）。稍后调用 get_sfx_task(task_id)（在托管服务上调用 get_generation_task(task_id)）；请参阅 task-recovery。

输出文件

单个文件：如果语音输入是音频，则为 .wav；如果语音输入是视频，则为 .mp4（已将压低音量后的混音重新封装到其中）。文件名与语音输入相同（例如，interview.mp4 → interview-ducked.mp4）；如果无法获取，则使用 ducked-<first 8 chars of the task id>。

错误处理

常见错误：401 密钥无效，402 余额不足／试用额度已用尽，413 文件过大，422 参数无效，429 请求频率超限。请参阅 account 技能。