video-to-sfx

Sonilo 视频转 SFX

交给 Sonilo 一段视频，它就会根据看到的内容生成匹配的音效——脚步声、撞击声、环境声、UI 音效，以及场景所需的其他音效；也可以使用 segments 将特定音效指定到特定时刻。生成任务会在后端异步运行；工具会在内部轮询，并返回已保存的文件。

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

⚠️ 费用： 以下每个工具都会发起可能产生费用的 API 调用。仅在明确收到请求时调用。

传输方式：MCP 或 CLI

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

1. 本会话中可见 Sonilo MCP 工具（video_to_sfx 等）——使用这些工具。这是首选方式：无需 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_sfx(
    video_path="~/Desktop/action-scene.mp4",
    prompt="Footsteps on gravel, distant traffic, a door slam"
)

Python（pip install sonilo）

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

foley = client.video_to_sfx.generate(video="action-scene.mp4", prompt="Footsteps on gravel, distant traffic, a door slam")
foley.save("foley.wav")

# video_to_video_sfx: get the video back with the effects muxed in
video = client.video_to_video_sfx.generate(video="action-scene.mp4", segments=[{"start": 0, "end": 2, "prompt": "footsteps on gravel"}])
video.save("with_sfx.mp4")

JavaScript / TypeScript（npm install sonilo）

import { SoniloClient } from "sonilo";

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

const foley = await client.videoToSfx.generate({
  video: "./action-scene.mp4",
  prompt: "Footsteps on gravel, distant traffic, a door slam",
});

// video_to_video_sfx: get the video back with the effects muxed in
const video = await client.videoToVideoSfx.generate({
  video: "./action-scene.mp4",
  segments: [{ start: 0, end: 2, prompt: "footsteps on gravel" }],
});

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

sonilo video-to-sfx --video action-scene.mp4 --output foley.wav

底层始终采用异步方式运行——CLI 会为你提交任务并进行轮询。--format 接受 wav|mp3|aac|flac。

# the muxed video, from the CLI
sonilo video-to-video-sfx --video clip.mp4 --prompt "footsteps, distant thunder" --output foley.mp4

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

curl -X POST "https://api.sonilo.com/v1/video-to-sfx" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Footsteps on gravel, distant traffic, a door slam"
# -> {"task_id": "..."}  poll GET /v1/tasks/{task_id} until status is succeeded/failed

每次调用都基于任务：端点会返回 {"task_id": ...}（HTTP 202），任务的 status 进入终态后，再从 GET /v1/tasks/{task_id} 获取结果。MCP 工具会为你完成轮询，并直接返回保存路径——只有调用超时的情况下，你才会看到 task_id（请参阅 task-recovery）。

工具

工具	说明
video_to_sfx(video_path? | video_url?, prompt?, segments?, audio_format?, output_directory?)	生成与视频匹配的 SFX。仅返回音频（不包含源视频）。
video_to_video_sfx(video_path? | video_url?, prompt?, segments?, output_directory?)	功能相同，但会返回已混入 SFX 的新 .mp4 文件。

参数

参数	类型	默认值	说明
prompt	string	—	可选的整体描述（最多 2000 个字符）——省略后，Sonilo 会自行解读视频。
video_path	string	—	.mp4/.mov/.webm/.m4v/.gif（gif 必须为动画）——支持的格式范围比音乐工具窄。最长 480s（8 分钟），同时受账户上传大小上限限制。
video_url	string	—	视频的 HTTPS/HTTP URL。video_path 和 video_url 必须且只能指定其中一个。
segments	list[dict]	—	为特定时间范围编写 SFX 脚本：[{"start": float, "end": float, "prompt": str}, ...]。请参阅下方规则。最多 30 个片段。
audio_format	string	aac（.m4a）	wav、mp3、aac 或 flac。仅适用于 video_to_sfx（视频转视频始终输出 .mp4）。
output_directory	string	SONILO_MCP_BASE_PATH	绝对路径，或相对于基础路径的路径。

segments 规则

后端会在产生任何费用之前进行验证——无效列表会被拒绝并返回 422/400，且不会产生费用：

• 第一个片段的 start 必须为 0。
• 片段必须连续：每个片段的 end 必须等于下一个片段的 start。
• 每个 end 都必须大于对应的 start。
• 每个 prompt 都不能为空，且最多 200 个字符。
• 最后一个片段的 end 不得超过视频的实际时长。
• 总共最多 30 个片段。

提示词

无需提示词——模型会读取剪辑内容。质量取决于按时间分段的动作图谱：每一秒都要描述屏幕上有什么、由什么构成、正在做什么。视频素材是事实依据。

付费调用前：确认准确时长和现有音频，遵守 480 s 的上限（超出会被 422 拒绝，不会截断），并取得确认——失败的运行会自动退款，但你自行重试会产生新费用。

• 完整的调用前检查（检查视频、上限、额度、验证）：references/preflight.md
• 动作图谱编写技巧（场景底色、声音组合、材质词汇、分段规则）：references/sfx-prompting.md

工作流提示

• 将 prompt/segments 留空，让 Sonilo 读取整个视频并自行判断；需要将特定声音固定到特定时刻时（例如在 2.3s 处落下一拳、在 5.0s 处关门声），使用 segments。
• 想要将音效合入视频并取回成片？ 使用 video_to_video_sfx，而不是 video_to_sfx。
• **提示词：**描述要具体，并组合多个元素——“大雨落在铁皮屋顶上”胜过“下雨”。
• 不要将其与音乐混淆。 如需背景配乐或原声带，请改用 video-to-music。如需在一次均衡的单次付费调用中同时生成音乐和音效，请使用 video-to-sound。
• 没有视频素材？ text-to-sfx 仅根据描述生成单个片段。
• 不知道应该是什么声音？ 先运行 video-analysis：一次调用即可根据视频素材生成声音设计概要——按镜头划分的 sfx_segments，以及可直接使用的整段视频 sfx_prompt（除非传入 mode="sfx"，否则还会提供音乐概要）——比猜提示词后反复重试更好。这是一次付费调用，但不会生成任何内容，因此只在确实不清楚概要时使用——如果用户已经说明想要什么，就不要使用。

超时调用的恢复

这里的每个工具在后端本来就是异步的；长时间生成仍可能超过 TIME_OUT_SECONDS。如果发生这种情况，错误信息会附带 task_id——任务会继续运行（且已经收费）。稍后调用 get_sfx_task(task_id)——托管服务上的 get_generation_task(task_id)——即可获取结果；参见 task-recovery。

输出文件

• video_to_sfx：以请求的 audio_format 保存（.wav/.mp3/.flac，默认 aac 时为 .m4a），文件名根据提示词生成（转换为 slug 格式），或使用 sfx-<first 8 chars of the task id>。
• video_to_video_sfx：生成一个合入音效的 .mp4 文件。

错误处理

常见错误：401 密钥无效，402 余额不足／试用额度已用尽，413 文件过大，422 参数无效或 segments 格式错误，429 超出速率限制。参见 account 技能。