setup-api-key

Sonilo 设置

引导用户连接到 Sonilo。接入方式有多种，应根据用户的实际需求选择，而不是只选列表中排在最前面的方式：

方式	需要 API 密钥吗？	最适合
A. sonilo login（CLI 登录，凭据与本地 MCP 服务共用）	不需要 — 通过浏览器进行 OAuth	使用带浏览器的设备的任何人。登录一次即可用于 CLI 和 uvx sonilo-mcp，因此 MCP 配置中无需包含密钥。
B. 远程 OAuth MCP 插件（sonilo-claude-plugin，或本仓库的 Muse Code 插件）	不需要 — 通过 OAuth 登录	希望不在本地运行任何内容的 Claude Code 和 Muse Code 用户。支持全部工具。
C. API 密钥（SONILO_API_KEY）	需要	CI、容器、无头设备，以及更愿意持有密钥的任何人。适用于所有客户端。

选择方式：

• 使用带浏览器的设备和任意 MCP 宿主 → 方式 A。这是最简便的方式，且不会在配置文件中留下密钥。
• 使用 Claude Code 或 Muse Code，且不想在本地运行任何内容 → 方式 B。
• 没有浏览器（CI、容器、远程设备），或用户表示已经有密钥 → 方式 C。
• 完全不通过 Agent 工作（编写代码、编写 Shell 脚本） → 查看末尾的 方式 D；A–C 中的 MCP 配置不适用。

步骤 0：检查当前是否已正常工作（所有方式）

更改任何内容之前先执行此步骤 — 通常答案是“无需操作”。

有两种传输方式，任意一种正常工作就足够。得出尚未配置的结论 之前，请先分别检查两种方式。

1. MCP： 是否已连接 sonilo MCP 服务（能否调用任何 Sonilo 工具，例如 text_to_music 或 get_account_services）？如果可以，请调用免费的只读工具 get_account_services()。
2. CLI： 如果没有 Sonilo 工具，请运行 sonilo account — 这是与上述相同的免费只读调用。退出代码为 0 表示 CLI 已安装、已登录且能够访问 API，技能可以直接驱动它。**不要用 sonilo whoami 进行检查：**即使在未登录时，它的退出代码也为 0，因此无法区分这两种状态；而且，如果账户没有显示名称，它会输出空的 account: 行，看起来就像凭据有问题。只有在需要显示当前活跃账户时才值得运行它，绝不能用它来判断登录状态。
3. **任意一种方式成功：**Sonilo 已配置且正常工作。告知用户并停止。只需询问他们是否想轮换凭据。
4. **返回 401：**认证信息已失效，而不是缺失。如果用户通过 sonilo login 登录，密钥可能已过期（90 天）或已撤销 — 再次运行 sonilo login 即可修复。否则，密钥有误：请转到方式 C。
5. **两种方式都无响应：**尚未连接任何方式 — 从下方选择一种并运行。MCP 是更好的默认选择（无需 Shell，而且它是唯一能在配音任务两小时的轮询期间保持连接的传输方式），但已安装并登录的 CLI 本身就是完整的配置；不要让用户配置他们不会使用的 MCP。

绝不要打印、引用或回显密钥或凭据文件的内容。如必须提及，请将其脱敏。

路径 A：sonilo login（无需 API 密钥，适用于任意 MCP 主机）

登录一次后，CLI 和本地 MCP 服务都会通过身份验证——CLI 会将凭据写入 ~/.config/sonilo/credentials.json，而 sonilo-mcp（0.16.0 及更高版本）会读取该凭据。

npm install -g sonilo-cli     # or: pip install sonilo-cli
sonilo login

CLI 会打印一次性代码，并在浏览器中打开 platform.sonilo.com。用户登录自己的 Sonilo Platform 账户（与面向消费者的 sonilo.com 账户分开），确认代码与终端打印的代码一致，然后批准。在没有浏览器的机器上，添加 --no-browser，并让用户通过其他设备批准打印出的 URL。

然后添加 MCP 服务，配置中不包含密钥：

claude mcp add sonilo -- uvx sonilo-mcp     # Claude Code
codex mcp add sonilo -- uvx sonilo-mcp      # Codex

对于 Claude Desktop，完整配置如下：

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

两者都需要 uv 包管理器（提供 uvx）：使用 brew install uv（macOS）、pipx install uv / pip install uv 或 winget install --id=astral-sh.uv（Windows）安装；其他安装方式见 https://docs.astral.sh/uv/getting-started/installation/。

建议提前告知用户：

• 批准后，系统会在用户账户中创建一个普通 API 密钥，名称为 cli: <hostname>，有效期为 90 天；用户可在 https://platform.sonilo.com/dashboard/api-keys 查看并撤销该密钥。
• sonilo whoami 会显示当前使用的账户和来源；sonilo logout 会在服务端撤销密钥，然后在本地删除该密钥。
• 已导出的 SONILO_API_KEY 优先于登录凭据。 如果工具使用了意料之外的账户，请先检查该变量——设置了该变量时，sonilo whoami 会明确说明。
• 登录面向个人用户。Sonilo 会向已配置的账户／POC 账户发放密钥，这些用户无法使用 sonilo login；此类用户应选择路径 C。

按照第 0 步中的方式，使用 get_account_services() 进行验证。

路径 B：远程 OAuth 插件（Claude Code 或 Muse Code，无需 API 密钥）

claude
/plugin marketplace add sonilo-ai/sonilo-claude-plugin
/plugin install sonilo@sonilo

首次调用 Sonilo 工具时，浏览器会打开，引导用户登录 Sonilo Platform 账户（platform.sonilo.com，与面向消费者的 sonilo.com 账户分开）并批准访问。Claude Code 会将生成的令牌按用户存储在 OS 密钥链中；无需复制、粘贴或配置任何内容。随时可在 /mcp 中查看或断开连接。

该方式连接到一个托管端点（https://api.sonilo.com/mcp，OAuth 2.1 + PKCE），提供与本地服务相同的工具集（路径 A 和 C）：根据文本或视频生成音乐／音效、视频转视频音乐／音效、视频转音效、视频转视频音效、配音、音频闪避，以及账户／用量相关工具。对于其他 MCP 主机，或偏好自行持有和管理密钥的用户，路径 A 和 C 仍然更合适。

**Muse Code：**Sonilo skills 插件包含同一个托管服务，因此安装插件即可完成全部设置：

MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins marketplace add sonilo-skills https://github.com/sonilo-ai/skills
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins install skills@sonilo-skills
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins approve skills

approve 会启用 MCP 服务（Muse 默认会停用第三方插件的服务，直至用户批准）。首次调用 Sonilo 工具时，系统会要求用户使用同一 Sonilo Platform 账户登录。如果调用提示服务需要 OAuth 登录，请将 "mcp_servers": {"sonilo": {"transport": "streamable_http", "url": "https://api.sonilo.com/mcp"}} 添加到 ~/.config/muse/settings.json，然后运行 muse mcp login sonilo——Muse Code 1.4.0 只会登录列在此处的服务。

路径 C：API 密钥（CI、容器或按偏好选择）

第 1 步：获取 API 密钥

仅当路径 A 不适用时才选择此路径——例如没有浏览器、使用已配置的账户、用于 CI，或明确偏好自行持有密钥。请告知用户：

从控制台获取 Sonilo API 密钥：https://platform.sonilo.com/dashboard/api-keys

（还没有账户？请先在那里注册——自助注册账户在大多数端点上可免费生成几次，无需提供银行卡。）

获取密钥后（格式类似 sk-...），请告诉我，我会帮你连接——尽量不要直接把密钥粘贴到此聊天中；我会改为将其写入 MCP 服务配置。

第 2 步：连接 MCP 服务

用户获取密钥后，使用该密钥连接 sonilo MCP 服务。主机支持 CLI 时，优先使用 CLI 方式：

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

对于不支持该 CLI 的主机（Claude Desktop、Codex），直接编辑 MCP 配置：

Claude Desktop（claude_desktop_config.json）：

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

Codex（~/.codex/config.toml）：

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

[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk-..."

两者都需要 uv 包管理器（提供 uvx）。如果尚未安装，可使用 brew install uv、pipx install uv / pip install uv 或 winget install --id=astral-sh.uv（其他安装方式请参阅 https://docs.astral.sh/uv/getting-started/installation/）。直接编辑配置文件后，请告知用户重启主机应用（Claude Desktop/Codex）；在 Claude Code 中执行 claude mcp add 后，新配置会在下一次会话生效，无需重启。

第 3 步：验证

连接后，调用 get_account_services()：

• 成功： 确认 Sonilo 已配置并正常工作。提及 get_account_services() 还会显示每项服务剩余的免费试用次数。
• 失败（401）： 凭据有误。在此流程中，这表示密钥无效——请返回第 1 步的控制面板链接，并请用户提供正确的密钥。如果用户改用 sonilo login 登录，则该登录对应的密钥已过期或被撤销：再次运行 sonilo login。
• 完全没有 Sonilo 工具： MCP 服务本身未连接——请重新检查第 2 步中的配置位置，并确认主机已重启或重新加载。

路径 D：Python/JS SDK 或 CLI（非 MCP）

并非所有集成都通过 MCP 主机进行。如果用户正在编写代码或通过 shell 编写脚本：

pip install sonilo          # Python SDK
npm install sonilo          # JS/TS SDK
pip install sonilo-cli      # Python-distributed CLI
npm install -g sonilo-cli   # npm-distributed CLI

使用与路径 C 相同的 API 密钥——从 https://platform.sonilo.com/dashboard/api-keys 获取，并将其设置为环境变量 SONILO_API_KEY（两个 SDK 和两个 CLI 都会自动读取；无需 MCP 配置、claude mcp add 或安装插件）。使用 SDK 自带的账户调用（client.account.services() / sonilo.account.services()）或在 CLI 中运行 sonilo account 进行验证。

可选配置（本地 MCP 服务）

仅在与用户的需求相关时提及这些配置——它们都有合理的默认值：

变量	默认值	适用情况
SONILO_API_URL	https://api.sonilo.com	仅用于非默认部署。
SONILO_MCP_BASE_PATH	~/Desktop	生成的文件默认保存的位置，也是相对输入路径的基准路径。如果用户希望将输出保存到其他位置，建议修改此项。
SONILO_MCP_ALLOW_ANY_PATH	false	仅当用户需要读写 SONILO_MCP_BASE_PATH 之外的文件时才设为 true——建议这样做前，先说明这会扩大工具的文件系统访问范围。
TIME_OUT_SECONDS	600	流式音乐、上传和下载的单次请求超时时间。基于任务的工具（SFX、音效、ducking、异步音乐）无论如何都会轮询至少 45 分钟，因为任务可能需要等待上游容量这么久。如果用户在长时间流式生成时遇到超时，可调高此值——请注意，无论此设置如何，get_sfx_task / get_generation_task（参见 task-recovery）始终可以恢复超时结果。

安全规则

• 如果可以通过配置文件或 claude mcp add 配置，绝不要要求用户直接在聊天中粘贴 API 密钥、令牌或机密信息。
• 配置完成后，绝不要打印或回显密钥的值。
• 引导用户前往控制面板（https://platform.sonilo.com/dashboard/api-keys）创建或轮换密钥，并前往 https://platform.sonilo.com/dashboard/billing 进行账单管理或充值——绝不要编造这两个 URL 的内容。