已有成片视频需要原创配乐时：按画面节奏/动作/情绪生成同步配…

当用户有一段已剪好的视频、需要生成与剪辑节奏对齐的原创配乐（既要音频，也要可直接使用的新视频）时使用。

适用场景

解决思路

1. 会话开始就选一种传输方式并全程保持不变、不要混用、也不要向用户宣告选择：优先用本会话可见的 Sonilo MCP 工具（如 `video_to_music`），因为它不需要 shell，且是唯一能扛住超长生成的路径。
2. 若 MCP 调用是认证失败（而不是输入参数失败），说明该传输在本会话不可用，改用 CLI；用 `sonilo account` 探测（不要用 `sonilo whoami`，它登出时也返回 0，无法区分两种状态）。
3. 两条传输都不可用时停下，先跑 setup-api-key 技能完成连接与认证；不要用 curl 直接打 `api.sonilo.com` 绕过，上传、轮询和重试都由这两条传输处理。
4. MCP 调用写法：`video_to_music(video_path="~/Desktop/trailer.mp4", prompt="Build suspense, then resolve with a warm cinematic finish")`；生成文件保存到 `SONILO_MCP_BASE_PATH`（默认 `~/Desktop`），返回保存路径文本。
5. Python：`pip install sonilo`；`client = Sonilo()`（读 `SONILO_API_KEY`）；`score = client.video_to_music.generate(video="trailer.mp4", prompt="...")`，再 `score.save("score.m4a")`；要带音乐的视频则用 `client.video_to_video_music.generate(...)` 后 `video.save("scored.mp4")`。
6. JavaScript/TypeScript：`npm install sonilo`；`new SoniloClient()`（读 `SONILO_API_KEY`）；`await client.videoToMusic.generate({video: "./trailer.mp4", prompt: "..."})`；带音乐视频用 `await client.videoToVideoMusic.generate({...})`。
7. CLI：`sonilo video-to-music --video trailer.mp4 --prompt "..." --output score.m4a`；`--format wav`、`--preserve-speech`、`--isolate-vocals` 会把该命令切到异步 submit-and-poll 路径；带音乐视频用 `sonilo video-to-video-music --video trailer.mp4 --prompt "..." --output scored.mp4`。
8. cURL 直连 REST：`curl -X POST "https://api.sonilo.com/v1/video-to-music" -H "Authorization: Bearer $SONILO_API_KEY" -F "video=@trailer.mp4" -F "prompt=..." --output score.m4a`；也可用 `video_url` 表单字段替代上传文件，两者只能传一个，不能都传。
9. 输入视频支持 `.mp4/.mov/.avi/.wmv/.webm/.mkv`，最长 360s（6 分钟），并受账号上传大小上限约束（通常 300MB）；`video_path` 用绝对路径或相对 `SONILO_MCP_BASE_PATH` 的路径。
10. 需要把生成的音乐拆成乐器分轨时，在 `video_to_music` 上加 `stems=true`（免费）：额外返回 `drums`、`bass`、`vocals`、`other` 四轨，与未改动的完整混音并列放在结果的 `stems` 数组中；REST 上必须 `mode=async` 否则 400，MCP 工具本身总是异步所以直接可用。
11. 使用 stems 时：它拆的是生成的音乐、绝不是源视频音频（`vocals` 轨通常近乎静音，属正常）；用 `stream_index` 而不是数组下标去对应各条音轨（分离失败的流会直接缺失，`stems` 可能比 `audio` 短）；出现 `stems_error` 不等于生成失败，缺失分轨只当少了个附加物，不要重试或要求退款；分离在生成完成后跑，通常再花 2–6 分钟，超过 30 分钟放弃并给出 `stems_error`；四轨名称固定（htdemucs，钢琴/合成器/吉他/弦乐都归入 `other`）；以每个 stem 的 `content_type` 为准判断实际交付格式。
12. 源视频里有想保留的对白/旁白时设 `preserve_speech=true`：在 `video_to_music` 上会同时返回音乐、隔离的语音干声（`vocals`）以及一份现成混好的 `mux`（语音+音乐），直接用 mux，不要自己重新混；该参数让调用走异步（submit + poll）会稍慢，但工具仍会等到完成。
13. 在 `video_to_video_music` 上 `preserve_speech` 没有单独的干声或 mux 文件，只是让源语音在单个输出视频里保持可听。
14. 想要「视频本身带配乐」就改用 `video_to_video_music`：输入相同，但输出是新的 `.mp4` 而不只是音频；要提醒用户默认会丢弃源音频——若视频有对白、旁白或音效需要保留，传 `keep_original_sound=true`（再加 `ducking=true` 让人声压在音乐之上），或只保留隔离语音时用 `preserve_speech=true`；用户反馈「有音乐但我的旁白没了」永远是这一条。
15. `ducking`：`video_to_music` 上服务端默认开启，`video_to_video_music` 上默认 `false`；免费、best-effort；在 `video_to_video_music` 上它只有在配合 `keep_original_sound` 或 `preserve_speech` 时才起作用（否则输出里根本没有源人声可压）。
16. 一次拿多个不同方向：`variants_num` 取 1–10，一次请求产出多个不同创作方向而非同一条重渲染；成本按数量线性叠加，且大于 1 时永不包含在免费试用里，调用前先跟用户确认数量。
17. `prompt_influence` 取 0–1（API 默认 0.5）：越低越让画面本身主导，越高越严格遵循提示词；免费，且不改变模式或产出文件数，用户没明确要求更严/更松就别动它。
18. `output_format` 只属于 `video_to_music`，默认 `m4a`，可设 `wav`；`video_to_video_music` 没有该参数，总是输出已混入音乐的 `.mp4`。
19. `output_directory` 用绝对路径，或相对 `SONILO_MCP_BASE_PATH` 的路径。
20. 付费调用前做 pre-flight：探测视频精确时长与现有音频、确认不超过 360s 上限（超出是 422 拒绝，绝不会截断）、拿到用户签字确认；失败运行会自动退款，但自己的重试是新的一笔计费——所以先把 brief 写好，只生成一次，之后迭代 prompt 而不是重掷。
21. 提示词写法：prompt 可选，模型会自动读画面；短的结构化 brief 用来补画面承载不了的意图——曲风、必须命中的时刻、绝不能出现的声音；prompt 中不得引用具体艺人、乐队或受版权保护的歌词。
22. 时长会自动匹配源视频，不要向模型索要或设置时长。
23. 同一视频要同时生成音乐和音效、且希望一次均衡计费时，用 video-to-sound，而不是分别调用本技能和 video-to-sfx。
24. 不知道该怎么描述听感时，先跑 video-analysis：一次调用返回分段方案和从画面读出的可直接使用的生成提示（除非传 `mode="music"`，否则还返回声音设计 brief），比瞎猜 prompt 再重掷强；它是付费但不产出内容的调用，只在 brief 确实不清楚时用。
25. 每次调用都可能产生费用，只在用户确实提出生成需求时才调用；不确定免费试用额度是否用完时先查 `get_account_services`（见 account 技能）。
26. 超时恢复：不带 `preserve_speech`/`ducking`/`stems`/`output_format="wav"` 的 `video_to_music` 是单次流式返回；任何触发后端异步模式的变体，以及总是异步的 `video_to_video_music`，都可能在 `TIME_OUT_SECONDS` 很长时超时。超时错误里带 `task_id`，后端仍在继续跑且已经计费；稍后调用 `get_sfx_task(task_id)`（托管服务器上是 `get_generation_task(task_id)`）取回结果。
27. 输出文件名规则：`video_to_music` 默认 `.m4a`（可 `.wav`），按 prompt slug 化命名或 `sonilo-<timestamp>.m4a`，多并行流加 `-<index>` 后缀；`preserve_speech=true` 时另存 `<base>-vocals.<ext>`（隔离语音）和 `<base>-mux.<ext>`（语音+音乐，真正该用的那个）；`video_to_video_music` 输出单个 `.mp4`。
28. 常见错误处理：401 密钥无效、402 余额不足/试用耗尽、413 文件过大、422 参数非法（如视频超过 360s 上限）、429 限流；调用前用 account 技能查试用与用量，具体恢复步骤见 sonilo-mcp README 的错误表。

适用边界 · 注意事项

• 没有视频、只想生成纯音乐时，改用 text-to-music 技能。
• 没有 Sonilo 连接或凭据（MCP 未连接、`sonilo account` 非 0、也没有 `SONILO_API_KEY`）时，先跑 setup-api-key 技能，不要用 curl 硬绕。
• 同一视频既要音乐又要音效、且希望一次均衡计费时，用 video-to-sound 而不是本技能。