Sonilo Music & Sound Effects

Sonilo MCP 服务

一个 MCP（Model Context Protocol）服务，可向兼容 MCP 的客户端（Claude Code、Claude Desktop、Codex）提供 Sonilo 的授权音乐和音效 API。

旗舰工具是 video_to_music：将成片交给它，它便会创作与剪辑相匹配的原创配乐——由于模型看到了视频，音乐会跟随视频的节奏、情绪和剪辑变化。音乐时长会自动匹配视频。每首曲目均已获授权，可安全用于商业用途（适用相关条款）。此外还提供 text_to_music，可在没有视频供其匹配时生成固定时长的曲目。

在声音设计方面，video_to_sfx 会分析视频并生成与之匹配的音效，以独立音频文件的形式返回。text_to_sfx 则可根据描述生成独立音效。

▶ 示例结果 —— 一支由 AI 生成的预告片，其配乐由 video_to_music 根据剪辑成片创作。如需了解适用于各种 AI 视频工作流（拼接 → 调色 → 添加音乐 → 混流）的配方，请参阅 Sonilo 视频配乐指南。

使用 Claude Code 快速开始

先通过 CLI 登录一次，然后在配置中添加服务，无需填写密钥：

npm install -g sonilo-cli && sonilo login
claude mcp add sonilo -- uvx sonilo-mcp

或者自行保管 API 密钥——请从 Sonilo 控制台获取：

claude mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp

然后启动会话并提出请求，例如：“为这个视频制作匹配的背景音乐：~/Desktop/promo.mp4。”

为什么选择 Sonilo

• 视频转音乐 — 提供视频，Sonilo 就会根据视频的节奏、动作和情绪创作一段完整长度的配乐。过渡和节拍变化会与剪辑点对齐，曲目时长也会与视频完全一致 — 无需提示词或手动同步。
• 文本转音乐 — 根据文本描述（流派、情绪、节奏、乐器）生成曲目，可指定精确时长（5–360s），也可不指定；此时 Sonilo 会选择适合提示词的时长。
• 视频转音效 — Sonilo 会分析视频，并为画面中的内容生成音效。生成的音效会以独立音频文件形式提供。可选的 segments 参数让你能够为指定时间范围编写音效脚本（[{start, end, prompt}]）。
• 文本转音效 — 根据描述生成独立音效（0.5–180s），支持 wav、mp3、aac 或 flac 格式。
• 配音前校对 — proofread 会转录视频，并将转录内容翻译成可编辑的 .srt 文件，每种语言各一份，另附源语言转录文件。阅读并更正文字后，再将文件作为 subtitles 交给 dubbing，即可确保配音内容与核准文本完全一致 — 在你确认之前，不会为任何内容配音。
• 完整授权，适用于商业用途 — 音乐通过 Shutterstock 授权；所有生成的曲目均获准用于社交媒体、品牌内容和广告等商业用途，无需担心 Content ID。
• 视频转声音 — 一次调用即可为同一段视频生成音乐和音效，并混合成平衡的单条音轨。获取混合后的音频，或获取已混入音轨的新视频。
• 每次调用生成多个变体 — text_to_music、video_to_music、video_to_video_music、video_to_sound 和 video_to_video_sound 支持 variants_num（1–10，默认值为 1）：一次请求即可生成多个不同的创意方向，无需逐个重新生成。费用随 N 线性增长，且 N > 1 不包含在免费试用中。
• 乐器分轨 — text_to_music 和 video_to_music 支持 stems=true：生成的曲目还会额外拆分为鼓、贝斯、人声和其他声部，不收取额外费用。分轨会多花几分钟；对于 video_to_music，拆分的是生成的音乐，而不是视频原有的音频。
• 按需付费 — 只按生成的音乐秒数计费。自助服务账户的每个端点均有免费调用额度，无需提供银行卡：文本转音乐、文本转音效、音频闪避和校对各 2 次；视频转音乐、视频转音效、视频转视频音乐、视频转视频音效、视频转声音和视频转视频声音各 1 次。之后的调用按标准费率计费。dubbing 有一次免费调用，即15 秒预览：首次不带 subtitles 的单语言调用，只会为视频的前 15 秒配音。之后按 视频时长 × 语言数量 计费（请参阅下文的免费试用）。

音频播放依赖项

play_audio 工具运行时需要 PortAudio（用于 sounddevice）。在 macOS/Linux 上，可通过以下方式安装：

• macOS：brew install portaudio
• Debian/Ubuntu：sudo apt-get install libportaudio2

uvx sonilo-mcp 和 pip install 会安装 Python 绑定，但必须单独安装系统 PortAudio 库。其他工具（text_to_music、video_to_music、text_to_sfx、video_to_sfx、audio_ducking、get_sfx_task、get_account_services、get_usage）无需 PortAudio 即可使用。

使用 Claude Desktop 快速入门

1. 进行身份验证，任选一种方式：

   • 使用 CLI 登录 — npm install -g sonilo-cli && sonilo login — 并将下方的 "env": {} 保持不变。配置文件中无需写入任何密钥。
   • 或从 Sonilo 控制台获取 API 密钥，并将其填入 "env"。

2. 安装 uv 包管理器（提供 uvx）：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   其他安装方法请参阅 uv 仓库。

3. 前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json，并添加以下内容：

   {
     "mcpServers": {
       "sonilo": {
         "command": "uvx",
         "args": ["sonilo-mcp"],
         "env": {}
       }
     }
   }
   

   使用 sonilo login 登录后，这就是完整的配置。若要填入密钥，或修改默认设置：

   "env": {
     "SONILO_API_KEY": "sk-...",
     "SONILO_API_URL": "https://api.sonilo.com",
     "TIME_OUT_SECONDS": "600"
   }
   

4. 重启 Claude Desktop。 你应该会在工具菜单中看到 Sonilo 工具。

使用 Codex 快速入门

使用 CLI 登录（npm install -g sonilo-cli && sonilo login）后，只需运行一个命令即可完成设置：

codex mcp add sonilo -- uvx sonilo-mcp

或者自行填入密钥：

codex mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp

若要手动配置：

1. 从 Sonilo 控制台获取 API 密钥 — 如果已使用 sonilo login 登录，则可跳过此步骤。

2. 安装 uv 包管理器（提供 uvx）：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. 前往 Codex > Settings > MCP servers，填写以下内容：

或者也可以将服务添加到** ~/.codex/config.toml：

[mcp_servers.sonilo]
command = "uvx"
args = ["sonilo-mcp"]

# Omit this whole block when you have signed in with `sonilo login`.
[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk-..."
SONILO_API_URL = "https://api.sonilo.com"
TIME_OUT_SECONDS = "600"

4. 重启 Codex（或启动新会话），然后运行 /mcp，确认 sonilo 已连接且工具已列出。

使用示例

连接服务后，只需用自然语言向助手提出请求。例如：

• “为这个视频制作匹配的背景音乐：~/Desktop/promo.mp4。”
• “为 https://example.com/clip.mp4 配上宁静、氛围感十足的音乐。”
• “我把 AI 生成的视频片段拼接成了 ~/Desktop/trailer.mp4 — 添加一段与剪辑相匹配的配乐。”
• “使用 Sonilo mcp，为学习播放列表生成 30 秒轻快的 lo-fi 嘻哈音乐，并保存到我的 Desktop。”
• “使用 Sonilo 创作一首史诗般的管弦乐电影配乐，时长约 60 秒。”
• “我的账户可使用哪些 Sonilo 服务和额度？”
• “显示我过去 7 天的 Sonilo 用量。”
• “播放你刚生成的曲目。”

助手会调用匹配的工具（text_to_music、video_to_music、text_to_sfx、video_to_sfx、audio_ducking、get_sfx_task、get_account_services、get_usage 或 play_audio），并将生成的音频保存到你配置的输出目录。

配置

身份验证

如果已设置 SONILO_API_KEY，服务会使用其中的密钥；否则会使用 sonilo login 写入的凭据（~/.config/sonilo/credentials.json 或 $XDG_CONFIG_HOME/sonilo/）。环境变量会优先使用，这是有意为之：任何已设置该变量的配置在升级后仍会使用同一账户。

服务会根据自身的 SONILO_API_URL 查找凭据，因此测试环境服务不会读取生产环境的登录凭据。本服务只会读取该文件：若要续期，请重新运行 sonilo login（登录生成的密钥有效期为 90 天）；若要撤销密钥，请运行 sonilo logout。

环境变量

变量	默认值	描述
SONILO_API_KEY	（来自 sonilo login）	Bearer 令牌。仅当你未通过 CLI 登录时才需要。
SONILO_API_URL	https://api.sonilo.com	公共 API 基础 URL。
SONILO_MCP_BASE_PATH	~/Desktop	默认输出目录，也是相对输入路径的基准目录。同时也是路径限制边界（见下文）。
SONILO_MCP_ALLOW_ANY_PATH	false	设置为 true，允许工具读写 SONILO_MCP_BASE_PATH 之外的文件。
TIME_OUT_SECONDS	600	流式音乐生成（text_to_music，以及未设置 preserve_speech 的 video_to_music）、上传和下载的超时时间，单位为秒。与后端的流式读取超时保持一致。无论此变量设置为何值，基于任务的工具（音效、ducking、视频转视频、异步音乐、analyze_video、proofread）都会等待至少 2700 秒（45 分钟），因为后端允许任务在队列中等待最多 2400 秒；调高此值可延长等待时间。stems 至少等待 75 分钟，配音至少等待 2 小时。

某些 MCP 主机会设置自己的工具调用超时时间，可能会在等待结束前中断调用。任务仍会继续运行，且仍会计费：任务 ID 会显示在服务的 stderr 日志中，格式为 [sonilo-mcp] task submitted: <id>，使用 get_sfx_task("<id>") 即可获取结果——不会丢失任何内容。

文件访问与路径限制

默认情况下，文件工具（video_to_music 的输入、play_audio 和任何 output_directory）都仅限访问 SONILO_MCP_BASE_PATH。解析符号链接后 指向该目录之外的路径会被拒绝。这样可以限制客户端被诱骗读取或窃取任意 文件时造成的影响范围。若要取消此限制（例如，要读取磁盘其他位置的视频），请设置 SONILO_MCP_ALLOW_ANY_PATH=true。

工具

工具	描述	费用
text_to_music(prompt, duration?, output_format?, variants_num?, stems?, output_directory?)	根据文本提示词生成音乐。variants_num（1–10，默认值为 1）可在一次请求中生成指定数量的不同变体，每个变体都有自己的标题；N > 1 会自动强制使用后端的异步模式，且绝不适用免费试用。stems（默认值为 false）还会免费将曲目拆分并保存为四条独立的乐器轨道——鼓、贝斯、人声和其他；这会多花几分钟（调用最长等待 75 min），并自动强制使用后端的异步模式。结果中的 stems_error 说明仅免费分离失败或被跳过——音乐本身没有问题。	✅
video_to_music(video_path? | video_url?, prompt?, preserve_speech?, variants_num?, prompt_influence?, stems?, output_directory?)	生成与视频相匹配的音乐。最长时长为 360s（6 min）；受账户上传大小上限约束（通常为 300 MB）。preserve_speech（默认值为 false）会在结果中保留源语音——你还会获得一条 vocals 语音分轨和一个可直接使用的混流文件；启用后，调用会在内部使用后端异步生成模式，而非流式模式。variants_num（1–10，默认值为 1）的工作方式与 text_to_music 中相同。prompt_influence（0–1，API 默认值为 0.5）用于设置生成的音乐遵循提示词的程度；除非你希望提示词遵循程度更严格或更宽松，否则请省略此参数。免费，流式和异步模式均可使用。stems（默认值为 false）的工作方式与 text_to_music 中相同——它会拆分生成的音乐，不会拆分视频自身的音频。	✅
text_to_sfx(prompt, duration?, audio_format?, output_directory?)	根据文本生成音效。时长为 0.5–180s，可选——省略时长即可使用 Sonilo 自身的默认时长；格式支持 wav/mp3/aac/flac（默认值为 aac）。	✅
video_to_sfx(video_path? | video_url?, prompt?, segments?, audio_format?, output_directory?)	为视频生成音效；保存生成的音效音频。视频最长时长为 480s（8 min）。	✅
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=true 可保留完整的源音轨，并将音乐以固定音量混入其中；再添加 ducking=true 可在有人声时降低音乐音量；也可传入 preserve_speech=true，仅保留分离出的人声。keep_original_sound 的优先级高于 preserve_speech。输入必须包含 H.264/HEVC/VP9/AV1 编码（mp4、mov、m4v、webm）；不接受动画 gif 和 VP8 webm。视频最长时长为 360s（6 min）。variants_num（1–10，默认值为 1）会为每个变体保存一个 .mp4。prompt_influence（0–1，API 默认值为 0.5）用于设置生成的音乐遵循提示词的程度；除非你希望提示词遵循程度更严格或更宽松，否则请省略此参数。免费。	✅
video_to_video_sfx(video_path? | video_url?, prompt?, segments?, output_directory?)	为视频生成音效，并返回一个混入这些音效的新 .mp4。视频最长时长为 480s（8 min）。	✅
video_to_sound(video_path? | video_url?, music_prompt?, sfx_prompt?, segments?, preserve_speech?, ducking?, output_format?, variants_num?, output_directory?)	一次调用即可为视频生成音乐和音效，并保存混合后的音轨。只收取一次费用，而非两次；两层音频由后端平衡。ducking（默认值为 false）会将源视频自身的人声混入，并在人声出现时降低音乐音量——关闭时，结果仅包含生成的音乐和音效，不会有 music_processed 分轨。output_format（默认为 wav，也支持 m4a 或 320 kbps 的 mp3）用于设置合并音轨的容器格式；音乐和音效分轨保留各自的原生格式。视频最长时长为 480s（8 min）。variants_num（1–10，默认值为 1）会为每个变体保存一条混合音轨。	✅
video_to_video_sound(video_path? | video_url?, music_prompt?, sfx_prompt?, segments?, keep_original_sound?, preserve_speech?, ducking?, variants_num?, output_directory?)	与 video_to_sound 类似，但会返回一个混入混合音轨的新 .mp4。默认情况下，结果音频仅包含生成的音乐和音效——源视频自身的音频会被移除，因此结果也不会包含 music_processed 分轨。传入 keep_original_sound=true 可保留完整的源音轨（以固定音量混合；添加 ducking=true 可改为在混合音轨出现时降低源音轨音量）；也可传入 preserve_speech=true，仅保留分离出的人声。keep_original_sound 仅在此处接受，video_to_sound 不接受。视频最长时长为 480s（8 min）。variants_num（1–10，默认值为 1）会为每个变体保存一个 .mp4。	✅
dubbing(video_path? | video_url?, languages?, ducking?, lipsync?, subtitles?, export_srt?, output_directory?)	将视频配音为其他语言，并为每种语言保存一个配音后的 .mp4。languages 是语言代码列表（en、zh_cn、ja、ko、pt、pt_br、es、es_419、de、fr、it、ru、th、ar、tr、vi、id、ta、ml、kn、gu、pa_in、sd_in、hi）；省略时默认使用 ["zh_cn", "es", "fr"]。pt_br 表示巴西葡萄牙语，es_419 表示拉丁美洲西班牙语；普通 pt 和 es 不加限定，ar 也不加限定。pa_in 和 sd_in 分别表示印度使用的旁遮普语和信德语，是仅有的变体；hi 表示印地语。video_url 必须是 https——配音流水线会自行获取源视频。lipsync 默认值为 true：说话者的嘴部会重新渲染，以匹配配音语音。设置 lipsync=false 可使画面完全保持原样——视频会以原始分辨率和帧率返回，而非重新渲染；系统只会替换音频，因此嘴部动作仍与原语言相匹配；适用于画面中没有说话者的素材。subtitles 是每种目标语言对应的一份脚本——例如 {"es": "/path/es.srt", "fr": "https://.../fr.vtt"}；可以是本地 .srt/.vtt 路径或 https URL，内容为该语言的台词，将替代流水线自身的翻译；键必须与配音语言一致。export_srt（需要 subtitles）还会为每种语言返回一个重新定时的 .srt，与交付音频同步，且保留原有台词文本。视频最长时长为 300s（5 min）。按语言计费。首次不带 subtitles 的单语言调用可免费预览 15 秒（请参阅下文的免费试用）。	✅
proofread(video_path? | video_url?, languages?, source_language?, output_directory?)	转录视频并将脚本翻译为目标语言，为每种语言保存一份可编辑的 .srt，另附源语言转录稿。不会进行配音，也不会生成语音——这是 dubbing 之前的步骤：先修正文案，再将文件作为 subtitles 传给 dubbing。languages 接受与 dubbing 相同的语言代码；省略该参数或传入 []，则仅生成源语言转录稿。source_language 是可选的转录提示；省略时系统会检测语言，无论哪种情况都会报告检测到的代码。video_url 必须是 https，且视频必须包含音轨。视频最长时长为 300s（5 min）。按语言计费（仅转录的请求也按一种语言计费），最低计费时长为 10 秒。	✅
analyze_video(video_path? | video_url?, prompt?, variants_num?, mode?)	分析视频并返回一份创意简报——其中包含与时间对齐的 segments 方案，以及每个变体各一条可直接用于生成的 prompt。mode 默认值为 both，会在音乐简报旁添加声音设计简报（sfx_segments 和一条 sfx_prompt）；music 或 sfx 则只返回对应的一份简报，价格相同。不会生成任何内容，也不会写入文件：简报会以内联 JSON 的形式返回，可直接传入 video_to_music、video_to_sfx、video_to_sound 或对应的视频转视频工具。当你还不知道视频应该呈现怎样的声音时，可使用此工具。视频最长时长为 480s（8 min）；variants_num 为 1–5（默认值为 1），并且按简报数量计费，最低计费时长为 10 秒。	✅
audio_ducking(voice_path? | voice_url?, music_path? | music_url?, output_directory?)	在人声音轨下方压低音乐音量。人声输入可以是视频——压低后的混音会重新混入新 .mp4。每个输入最长为 360s（6 min）；受账户上传大小上限约束。	✅
get_sfx_task(task_id, output_directory?)	检查音效、音频闪避、视频转视频、视频转声音、配音、校对、视频分析或异步视频转音乐任务并返回结果——用于恢复超时的 text_to_sfx、video_to_sfx、audio_ducking、video_to_video_music、video_to_video_sfx、video_to_sound、video_to_video_sound、dubbing、proofread、analyze_video 和 video_to_music(preserve_speech=true) 调用。analyze_video 任务没有可下载的文件，因此其简报会以内联形式返回；proofread 任务保存 .srt 文件的方式与直接调用相同；其他任务的结果都会保存到磁盘。	❌
get_account_services()	列出可用服务、限制，以及每项服务剩余的免费试用额度。	❌
get_usage(days=30)	显示使用情况摘要和逐日明细。	❌
play_audio(input_file_path)	播放本地音频文件。	❌
标有 ✅ 的工具会调用 API，并在你的 Sonilo 账户上产生费用。

每个工具还带有 MCP 工具注释，因此客户端无需阅读描述就能区分这两类工具：get_account_services、get_usage 和 play_audio 是只读工具；其他所有工具都会写入文件或产生费用，且都不会造成破坏（输出绝不会覆盖现有文件）。服务的 instructions 会指示 Agent 在首次付费调用前检查 get_account_services，并在调用超时后通过 get_sfx_task 恢复。

**免费试用：**自助注册账户在每项服务开始时都会获得少量免费调用次数——无需银行卡。get_account_services() 会通过 trial[service] = {granted, used, remaining} 报告剩余次数；调用标有 ✅ 的工具前请先检查，以便提醒用户，而不是让调用失败。某项服务的 remaining 降至 0 时，在添加付款方式之前，对该服务的调用都会因 trial_exhausted 而失败。配音只有 1 次免费调用，且为 15 秒预览：首次不带字幕的单语言调用只会免费翻译视频的前 15 秒，结果中会包含 trial_preview，显示完整视频的费用；proofread 有 2 次免费调用，和配音一样，按语言计费。没有免费试用额度的账户不会包含 trial 键。

**可选：**如果已安装 ffprobe（FFmpeg 的一部分），video_to_music 会在本地检查视频时长，并在上传前拒绝时长超过 360 秒的视频。video_to_sfx 也会执行相同的本地检查，时长上限为 480 秒。audio_ducking 会对两个输入执行相同检查，时长上限为 360 秒。如果未安装，后端仍会强制执行相同限制。

音效和闪避处理以任务形式运行

音乐工具会流式传输结果，并在一次调用中完成——只有一种例外：video_to_music(preserve_speech=true) 会提交一个任务，并在内部轮询，而不是直接处理，因为只有在后端异步模式下才能保留原始语音。一次调用仍会返回已保存的文件路径；你只是不必看到任务，而且和音效工具一样，如果调用超时，也会使用相同的 get_sfx_task 恢复流程。音效工具会提交一个任务，然后轮询直到任务完成——text_to_sfx 和 video_to_sfx 会替你完成这些步骤并返回已保存的文件路径，因此通常无需看到任务。audio_ducking 也使用相同的先提交再轮询流程，以及相同的 get_sfx_task 恢复流程。

如果调用超时，生成仍会继续运行（并且费用已产生）。错误消息会包含任务 ID，任务准备就绪后，可通过 get_sfx_task("<id>") 获取结果。任务提交后，也会立即将任务 ID 输出到 stderr，因此即使调用被取消，该 ID 也会保留下来。可以安全地重复调用 get_sfx_task：如果文件已在磁盘上，它会报告文件已存在，而不会再次下载。

输出格式

音乐会保存为 .m4a（MP4 容器中的 AAC）。文件名使用后端返回的标题（转换为 slug 格式）；如果没有标题，则使用 sonilo-<timestamp>.m4a 作为备用文件名。返回多个并行流时，文件名会附加 -<index> 后缀。

video_to_music(preserve_speech=true) 最多会保存三种文件，返回文本会分别标明：生成的音乐音频（命名规则同上，使用 prompt；若没有，则使用 music-<first 8 chars of the task id>）、保留的语音音轨（<base>-vocals.<ext>），以及混音文件——即语音和音乐已混合在一起、可直接使用的成品（<base>-mux.<ext>；多个流时为 <base>-mux-<index>.<ext>）。语音音轨和混音文件的扩展名由后端报告的 content_type 决定（通常为 .m4a）。

音效会按请求的 audio_format 保存，格式可为 wav、mp3、flac 或 aac（默认格式，保存为 .m4a）；video_to_sfx 只保存音频，不保存源视频。 混合音频（video_to_sound / video_to_video_sound）会保存为一个文件：video_to_sound 保存为 .wav，video_to_video_sound 保存为 .mp4。文件名取自 music_prompt，若没有则依次回退到 sfx_prompt，再回退到 sound-<first 8 chars of the task id> / v2v-sound-<first 8 chars of the task id>。单独的音乐和 SFX 分轨会保留在后端，只有混音结果会被下载。

多个变体（在 text_to_music、video_to_music、video_to_video_music、video_to_sound、video_to_video_sound 中设置 variants_num > 1）会为每个变体分别保存一个文件，而不是只保存一个文件，并按请求顺序添加 -0、-1、… 后缀（例如，<base>-0.m4a、<base>-1.m4a）。对于音乐工具，每个变体都是独立的创作方向；如果后端提供标题，返回文本会注明对应变体。费用会随 variants_num 线性增长，即使使用免费试用账户，任何大于 1 的值也会按完整费用计费。超时的多变体调用可通过 get_sfx_task 恢复所有变体，与单变体调用相同。

分轨（在 text_to_music / video_to_music 中设置 stems=true）会为每个生成的音轨额外保存四个文件：<base>-stems-drums.<ext>、-stems-bass、-stems-vocals、-stems-other（当 variants_num > 1 时，会将变体索引并入文件名，格式为 <base>-stems-<index>-<name>.<ext>），与未经处理的完整音轨一同保存。分轨免费提供，且尽力而为：通常会额外耗时 2–6 分钟（调用最多等待 40 分钟）。如果分轨失败或被跳过，结果会附带 stems_error 说明，而不是分轨文件；也可能只返回部分分轨文件。音乐本身不会受影响，仍会完整交付。

配音（dubbing）会按请求的每种语言保存一个 .mp4，命名为 dubbing-<first 8 chars of the task id>.<language>.mp4——没有提示词可用于命名文件。设置 export_srt 后，每种语言重新调整时间轴的脚本会保存在对应视频旁边，命名为 dubbing-<first 8 chars of the task id>.<language>.srt；返回结果会报告该语言的导出状态和对齐损失（如果导出受阻，还会附带问题代码和报告链接）。所有配音 .mp4 都会在第一个 .srt 之前下载；脚本被阻止或无法下载时，会作为说明报告，而不是失败——缺少字幕不会导致视频无法交付。请求四种语言会生成四个文件，费用是请求一种语言的四倍。无论 TIME_OUT_SECONDS 设置为何值，配音轮询至少会持续两小时，以匹配后端对此任务的时限。

校对（proofread）会为结果中的每种语言保存一个 .srt，命名为 proofread-<first 8 chars of the task id>.<language>.srt——没有提示词可用于命名文件。文件集合始终包含检测到的源语言以及所有请求的目标语言，因此即使请求中没有 languages，也会写入一个文件。文件之后，返回文本会报告检测到的 source_language 和源脚本的 cue_count，然后为每条非阻塞警告提供一条说明（例如，某条字幕的文本播放速度过快，难以阅读）。警告不会阻止文件生成；某种语言的 .srt 无法下载时，会附带任务 ID 作为说明，而不是报错。编辑这些文件后，可将它们作为 subtitles 传给 dubbing，让配音采用已批准的措辞；配音的字幕键必须与配音语言一致，因此除非源语言本身也是目标语言，否则请不要包含源语言文件。

文件名取自提示词（转换为 slug 格式，并截断至 80 个字符）。没有提示词可用于命名文件时——例如，未提供提示词的 video_to_sfx，或通过 get_sfx_task 恢复的 SFX/ducking 文件——文件名会改为 sfx-<first 8 chars of the task id>。通过 get_sfx_task 恢复的 video_to_music(preserve_speech=true) 任务，文件名会改为 music-<first 8 chars of the task id>（get_sfx_task 会检测音乐包络形状，并像直接调用 video_to_music 一样保存音频、人声和复用文件）。不会覆盖现有文件：如果文件名已存在，会改为添加 -1、-2、… 后缀。 Ducking 结果会保存为单个文件：.wav；如果语音输入是视频，则保存为 .mp4（ducking 后的混音会重新复用到视频中）。文件名为语音输入的名称加上 -ducked（例如，interview.mp4 → interview-ducked.mp4）；如果没有可用的名称，则使用 ducked-<first 8 chars of the task id>。通过 get_sfx_task 恢复的 ducking 结果会改用 sfx-<first 8 chars of the task id> 命名，因为该工具没有语音文件名可用。

常见错误

消息	处理方法
SONILO_API_KEY not set and no stored credential found	运行 sonilo login，或在服务端的配置中设置 SONILO_API_KEY。
Invalid SONILO_API_KEY	在 https://platform.sonilo.com/dashboard/api-keys 验证密钥。如果你通过 CLI 登录，密钥可能已过期（90 天）或已被撤销——请重新运行 sonilo login。
Insufficient minutes / Credit limit exceeded	在 https://platform.sonilo.com/dashboard/billing 充值。
You've used your N free trial calls for <service>	该服务的免费试用次数已用完。请在 https://platform.sonilo.com/dashboard/billing 添加付款方式——重试无济于事。get_account_services 会显示其他服务的剩余次数。
Rate limit exceeded: your account allows N requests per minute	调用速度过快。计数器按固定的 60 秒窗口运行，被拒绝的调用也会计入，因此请等待当前窗口结束，而不要在窗口内重试。get_account_services 会报告你的 rpm_limit；如需提高限额，请发送邮件至 [email protected]。
Too many concurrent generations: N of N in progress	所有生成槽位都在使用中。仅仅等待不会释放槽位——必须先有正在运行的生成任务完成。get_account_services 会报告你的 concurrency_limit；如需提高限额，请发送邮件至 [email protected]。
Generation timed out（音乐，text_to_music/video_to_music 未设置 preserve_speech）	增大 TIME_OUT_SECONDS。检查 get_usage，确认后端是否已完成并扣费。
Timed out … waiting for task <id>（SFX、ducking 或 video_to_music(preserve_speech=true)）	生成仍在运行。调用 get_sfx_task("<id>") 获取结果——不会丢失任何内容，包括超时的 preserve_speech 音乐任务（get_sfx_task 会识别其结果格式，并以与 video_to_music 本身相同的方式保存音频/人声/复用视频）。
Task not found	任务 ID 不存在，或属于纯流式生成（text_to_music，或未设置 preserve_speech 的 video_to_music），无法轮询。请检查 ID。