已有视频需要声音设计时，用 Sonilo…

为已有视频生成匹配画面的音效（脚步、撞击、环境声、拟音），可按时间段指定声音，并返回音频或带音效的新视频。

适用场景

解决思路

1. 选择传输方式：会话开始时在 MCP 与 CLI 中选一个并全程使用；不要在同一任务里混用，也不要宣布选择。优先使用当前会话可见的 Sonilo MCP 工具（如 `video_to_sfx`）；它无需 shell，且是唯一能承受超长生成的路径。若 MCP 调用因认证失败（而非输入失败），不要重试，改用 CLI。若没有可用 MCP 工具但 `sonilo account` 退出码为 0，使用 CLI 命令；探测用 `sonilo account`，不要用 `sonilo whoami`，因为未登录时 whoami 也返回 0。若两者都不可用，停止并运行 `setup-api-key` 技能；不要用 curl 直接调用 `api.sonilo.com` 绕过传输层，因为传输层会处理上传、轮询和重试。
2. 费用控制：下面每个工具都会发起可能计费的 API 调用；仅在明确请求时调用。
3. 使用 MCP 调用生成音频：`video_to_sfx(video_path="~/Desktop/action-scene.mp4", prompt="Footsteps on gravel, distant traffic, a door slam")`。
4. 使用 Python SDK：`pip install sonilo`；`from sonilo import Sonilo`；`client = Sonilo()` 读取 `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")`。
5. 使用 Python 获取混入音效的视频：`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")`。
6. 使用 JS/TS SDK：`npm install sonilo`；`import { SoniloClient } from "sonilo"`；`const client = new SoniloClient()` 读取 `SONILO_API_KEY`；`const foley = await client.videoToSfx.generate({ video: "./action-scene.mp4", prompt: "Footsteps on gravel, distant traffic, a door slam" })`。
7. 使用 JS/TS 获取混入音效的视频：`const video = await client.videoToVideoSfx.generate({ video: "./action-scene.mp4", segments: [{ start: 0, end: 2, prompt: "footsteps on gravel" }] })`。
8. 使用 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`。
9. 使用 CLI 获取混入音效的视频：`sonilo video-to-video-sfx --video clip.mp4 --prompt "footsteps, distant thunder" --output foley.mp4`。
10. 使用 cURL 原始 REST API：`curl -X POST "https://api.sonilo.com/v1/video-to-sfx" -H "Authorization: Bearer $SONILO_API_KEY" -F "video=@action-scene.mp4" -F "prompt=Footsteps on gravel, distant traffic, a door slam"`；返回 `{"task_id": "..."}`；轮询 `GET /v1/tasks/{task_id}` 直到 `status` 为 succeeded/failed。每次调用都是基于任务的：端点返回 `{"task_id": ...}`（HTTP 202），结果在 `status` 终态后从 `GET /v1/tasks/{task_id}` 获取；MCP 工具会代做轮询并直接返回保存路径，只有超时才会看到 `task_id`（见 task-recovery）。
11. 选择工具：用 `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`。
12. 参数 `prompt`：可选，整体描述，最大 2000 字符；省略它让 Sonilo 自行解释视频。
13. 参数 `video_path`：支持 `.mp4/.mov/.webm/.m4v/.gif`（gif 必须为动图），比音乐工具支持的集合更窄；最大 180s（3 分钟），并受账号上传大小上限限制。
14. 参数 `video_url`：HTTPS/HTTP 视频 URL；`video_path` 与 `video_url` 必须且只能提供一个。
15. 参数 `segments`：用 `[{"start": float, "end": float, "prompt": str}, ...]` 把 SFX 脚本化到特定时间范围；最多 30 个 segment。
16. 参数 `audio_format`：默认 `aac`（`.m4a`）；可选 `wav`、`mp3`、`aac`、`flac`；仅用于 `video_to_sfx`（video-to-video 始终输出 `.mp4`）。
17. 参数 `output_directory`：默认 `SONILO_MCP_BASE_PATH`；可为绝对路径，或相对于 base path。
18. 遵守 `segments` 规则：第一个 segment 的 `start` 必须为 `0`；segments 必须连续，每个 `end` 必须等于下一个 segment 的 `start`；每个 `end` 必须大于其 `start`；每个 `prompt` 必须非空且最大 200 字符；最后一个 `end` 不得超过视频实际时长；最多 30 个 segment。后端在计费前验证；无效列表会以 422/400 拒绝且不计费。
19. 提示词策略：无需 prompt，模型会读剪辑；质量来自按时间分段的动作映射——逐秒描述屏幕上有什么、由什么材质构成、在做什么。画面是事实来源。
20. 付费调用前预检：探测精确时长和已有音频，遵守 180s 上限（超出会 422 拒绝，绝不截断），并获得确认；失败运行会自动退款，但自己重试会产生新费用。完整预检见 `references/preflight.md`；动作映射技巧（场景底、声音包、材质词汇、segment 规则）见 `references/sfx-prompting.md`。
21. 工作流选择：不设置 `prompt`/`segments` 让 Sonilo 读取整段视频并自行决定；当需要把特定声音钉到特定时刻（例如 2.3s 的拳击落地、5.0s 的关门）时使用 `segments`。
22. 想要返回带 SFX 的视频时使用 `video_to_video_sfx`，而不是 `video_to_sfx`。
23. 提示词写法：具体并组合元素，“Heavy rain on a tin roof” 优于 “Rain”。
24. 不要与音乐混淆：背景配乐或原声用 `video-to-music`；要在一次平衡、单次计费调用中同时生成音乐和 SFX，用 `video-to-sound`。
25. 没有素材时：用 `text-to-sfx` 仅从描述生成单个片段。
26. 不知道应该是什么声音时：先运行 `video-analysis`，一次调用返回从画面读出的声音设计简报——按镜头大小的 `sfx_segments` 加上可直接使用的整段 `sfx_prompt`（除非传入 `mode="sfx"`，还会返回音乐简报）——比猜测 prompt 并反复重跑更好；它是不生成内容的付费调用，只在简报确实不清楚时使用，用户已说明想要什么时不要用。
27. 恢复超时调用：这里的每个工具后端已经异步；长生成仍可能超过 `TIME_OUT_SECONDS`。如果超时，错误会带上 `task_id`；任务继续运行（且已计费）。之后调用 `get_sfx_task(task_id)`（托管服务器上用 `get_generation_task(task_id)`）取回结果；见 `task-recovery`。
28. 输出文件：`video_to_sfx` 按请求的 `audio_format` 保存（`.wav`/`.mp3`/`.flac`，或 `aac` 默认的 `.m4a`），文件名来自 prompt（slugified）或 `sfx-<task id 前 8 个字符>`。`video_to_video_sfx` 输出单个混入 SFX 的 `.mp4`。
29. 错误处理：常见错误包括 `401` 无效 key、`402` 余额不足/试用耗尽、`413` 文件太大、`422` 无效参数或格式错误的 `segments`、`429` 速率限制；见 `account` 技能。

适用边界 · 注意事项

• 没有视频素材、只想从文字描述生成音效时，改用 text-to-sfx，不要用本技能。
• 需要背景配乐或音乐时，改用 video-to-music；需要一次调用同时生成音乐和音效时，改用 video-to-sound，不要用本技能。
• 不要在 MCP 与 CLI 都不可用时用 curl 直连 api.sonilo.com 绕过传输层；应先用 setup-api-key 完成认证。