setup-api-key

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sonilo Setup

Sonilo 设置

Guide the user through connecting to Sonilo. There are several ways in — pick based on what the user is actually doing, not just whichever is listed first:

Path	Needs an API key?	Best for
A. `sonilo login` (CLI sign-in, credential shared with the local MCP server)	No — OAuth in the browser	Anyone on a machine with a browser. One sign-in covers the CLI and `uvx sonilo-mcp` , so the MCP config carries no secret.
B. Remote OAuth MCP plugin ( `sonilo-claude-plugin` )	No — OAuth sign-in	Claude Code users who want nothing running locally. Full tool coverage.
C. API key ( `SONILO_API_KEY` )	Yes	CI, containers, headless boxes, and anyone who prefers holding a key. Works with every client.

Choosing:

On a machine with a browser and any MCP host → Path A. It is the shortest path and leaves no secret in a config file.
Claude Code specifically, and nothing local wanted → Path B.
No browser (CI, a container, a remote box), or the user says they already have a key → Path C.
Not working through an agent at all (writing code, scripting a shell) → Path D at the end; the MCP configuration in A–C does not apply.

引导用户完成Sonilo的连接流程。有多种连接方式，请根据用户实际操作场景选择，而非按列表顺序：

路径	是否需要API密钥	适用场景
A. `sonilo login` （CLI登录，凭证与本地MCP服务器共享）	无需——通过浏览器进行OAuth认证	所有使用带浏览器设备的用户。一次登录即可覆盖CLI和 `uvx sonilo-mcp` ，MCP配置无需存储密钥。
B. 远程OAuth MCP插件 ( `sonilo-claude-plugin` )	无需——OAuth登录	不想在本地运行任何程序的Claude Code用户。支持完整工具集。
C. API密钥 ( `SONILO_API_KEY` )	需要	CI、容器、无头服务器，以及偏好自行管理密钥的用户。适用于所有客户端。

选择建议：

设备带有浏览器且使用任意MCP主机 → 路径A。这是最简便的方式，且无需在配置文件中存储密钥。
专门使用Claude Code且不想在本地运行程序 → 路径B。
无浏览器（CI、容器、远程服务器），或用户表示已拥有密钥 → 路径C。
完全不通过代理操作（编写代码、脚本） → 最后选择路径D；A-C的MCP配置不适用此场景。

Step 0: Check what already works (all paths)

步骤0：检查现有可用配置（所有路径通用）

Do this before changing anything — the answer is often "nothing to do".

There are two transports, and either one is enough. Probe both before concluding that nothing is set up.

MCP: is a
```
sonilo
```
MCP server connected (any Sonilo tool, e.g.
```
text_to_music
```
or
```
get_account_services
```
, available to call)? If so, call the free, read-only
```
get_account_services()
```
.
CLI: if there are no Sonilo tools, run
```
sonilo account
```
— the same free, read-only call as above. Exit code 0 means the CLI is installed, signed in, and reaching the API, and the skills can drive it directly. Do not probe with
sonilo whoami
: it exits 0 even when signed out, so it cannot separate the two states, and on an account with no display name it prints an empty
```
account:
```
line that reads like a broken credential. It is worth running only to show which account is active, never to decide.
Either one succeeds: Sonilo is configured and working. Say so and stop. Ask only whether they want to rotate credentials.
Fails with 401: authentication is stale, not missing. If they signed in with
```
sonilo login
```
, the key may have expired (90 days) or been revoked —
```
sonilo login
```
again fixes it. Otherwise the key is wrong: continue at Path C.
Neither responds: nothing is connected — pick a path below and run it. MCP is the better default (it needs no shell, and it is the only transport that survives a dubbing job's two-hour poll), but a CLI that is installed and signed in is a complete setup on its own; do not make someone configure MCP they will not use.

Never print, quote, or echo a key or the contents of the credential file. If you must refer to one, redact it.

在进行任何更改前先执行此步骤——通常结果是“无需操作”。

有两种传输方式，任意一种可用即可。在判定未完成配置前，请先探测两种方式：

MCP： 是否已连接
```
sonilo
```
MCP服务器（是否可调用任意Sonilo工具，如
```
text_to_music
```
或
```
get_account_services
```
）？如果是，调用免费的只读接口
```
get_account_services()
```
。
CLI： 如果无Sonilo工具可用，运行
```
sonilo account
```
——这与上述免费只读接口相同。退出码为0表示CLI已安装、已登录且可连接API，技能可直接调用CLI。请勿使用
sonilo whoami
探测：即使未登录，它也会返回退出码0，无法区分两种状态；且对于无显示名称的账户，它会打印空的
```
account:
```
行，看起来像是凭证失效。仅在需要显示当前活跃账户时运行此命令，切勿用于判定配置状态。
任意一种方式成功： Sonilo已配置完成并可正常使用。告知用户并停止操作。仅询问用户是否需要轮换凭证。
返回401错误： 认证已过期，而非缺失。如果用户通过
```
sonilo login
```
登录，密钥可能已过期（90天）或被撤销——重新运行
```
sonilo login
```
即可解决。否则为密钥错误：继续执行路径C。
两种方式均无响应： 未建立连接——选择下方路径进行配置。MCP是更优的默认选择（无需Shell，且是唯一能在配音任务的两小时轮询中持续运行的传输方式），但已安装并登录的CLI本身就是完整配置；无需强制用户配置他们不会使用的MCP。

切勿打印、引用或回显密钥或凭证文件内容。若必须提及，请进行脱敏处理。

Path A:

sonilo login

(no API key, any MCP host)

路径A：

sonilo login

（无需API密钥，适用于任意MCP主机）

One sign-in, then both the CLI and the local MCP server are authenticated — the CLI writes a credential to

~/.config/sonilo/credentials.json

and

sonilo-mcp

(0.16.0 and later) reads it.

bash

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

The CLI prints a one-time code and opens the browser to platform.sonilo.com. The user signs in to their Sonilo Platform account (separate from a consumer sonilo.com account), confirms the code matches what the terminal printed, and approves. On a machine without a browser, add

--no-browser

and have them approve the printed URL from another device.

Then add the MCP server with no secret in the config:

bash

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

For Claude Desktop, the whole config is:

json

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

Both need the

uv

package manager (provides

uvx

): install it with

brew install uv

(macOS),

pipx install uv

pip install uv

, or

winget install --id=astral-sh.uv

(Windows) — other methods at https://docs.astral.sh/uv/getting-started/installation/.

Worth telling the user up front:

Approving mints an ordinary API key on their account, named
```
cli: <hostname>
```
, that expires after 90 days and is visible and revocable at https://platform.sonilo.com/dashboard/api-keys.
```
sonilo whoami
```
shows which account and source is active;
```
sonilo logout
```
revokes the key server-side and then forgets it locally.
An exported
SONILO_API_KEY
takes precedence over the sign-in. If tools authenticate as an unexpected account, check for that variable first —
```
sonilo whoami
```
says so explicitly when it is set.
Sign-in is for humans. Provisioned/POC accounts are issued a key by Sonilo and cannot use
```
sonilo login
```
; those users belong on Path C.

Validate with

get_account_services()

, exactly as in Step 0.

一次登录后，CLI和本地MCP服务器均会完成认证——CLI会将凭证写入

~/.config/sonilo/credentials.json

，

sonilo-mcp

（0.16.0及以上版本）会读取此凭证。

bash

npm install -g sonilo-cli     # 或：pip install sonilo-cli
sonilo login

CLI会打印一个一次性验证码并在浏览器中打开platform.sonilo.com。用户登录其Sonilo Platform账户（与普通sonilo.com账户分离），确认验证码与终端显示一致后授权。对于无浏览器的设备，添加

--no-browser

参数，让用户从其他设备打开打印的URL进行授权。

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

bash

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

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

json

{
  "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
```
会明确提示。
登录功能面向普通用户。预配置/POC账户由Sonilo发放密钥，无法使用
```
sonilo login
```
；此类用户应选择路径C。

通过

get_account_services()

验证配置，与步骤0中的操作完全一致。

Path B: Remote OAuth plugin (Claude Code only, no API key)

路径B：远程OAuth插件（仅适用于Claude Code，无需API密钥）

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

The first Sonilo tool call opens the browser to sign in to a Sonilo Platform account (platform.sonilo.com — separate from a consumer sonilo.com account) and approve access. Claude Code stores the resulting token per-user in the OS keychain; nothing to copy, paste, or configure. Review or disconnect anytime from

/mcp

This connects to a single hosted endpoint (

https://api.sonilo.com/mcp

, OAuth 2.1 + PKCE) that carries the same tool set as the local server (Paths A and C): music/SFX from text or video, video-to-video music/SFX, video-to-sound, video-to-video-sound, dubbing, audio ducking, and account/usage. Paths A and C are still the better fit for MCP hosts other than Claude Code, or for users who prefer holding and managing their own key.

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

首次调用Sonilo工具时会打开浏览器，让用户登录Sonilo Platform账户（platform.sonilo.com——与普通sonilo.com账户分离）并授权访问。Claude Code会将生成的令牌按用户存储在系统密钥链中；无需复制、粘贴或配置。可随时通过

/mcp

查看或断开连接。

此方式连接到单一托管端点（

https://api.sonilo.com/mcp

，OAuth 2.1 + PKCE），提供与本地服务器（路径A和C）相同的工具集：文本/视频生成音乐/音效、视频转视频音乐/音效、视频转音频、视频转视频音频、配音、音频闪避，以及账户/使用情况查询。对于非Claude Code的MCP主机，或偏好自行持有和管理密钥的用户，路径A和C仍是更优选择。

Path C: API key (CI, containers, or by preference)

路径C：API密钥（适用于CI、容器，或用户偏好）

Step 1: Get an API key

步骤1：获取API密钥

Only take this path when Path A does not fit — no browser, a provisioned account, CI, or an explicit preference for holding a key. Tell the user:

Get your Sonilo API key from the dashboard: https://platform.sonilo.com/dashboard/api-keys

(Need an account? Sign up there first — self-serve accounts start with a few free generation runs on most endpoints, no card required.)
Once you have a key (it looks like
sk-...
), tell me and I'll connect it — don't paste it directly into this chat if you can avoid it; I'll wire it into the MCP server config instead.

仅当路径A不适用时选择此路径——无浏览器、预配置账户、CI环境，或用户明确偏好自行管理密钥。告知用户：

从仪表盘获取Sonilo API密钥：https://platform.sonilo.com/dashboard/api-keys

（需要账户？先在此注册——自助账户初始包含多项免费生成额度，无需绑定银行卡。）
获取密钥后（格式为
sk-...
），告知我即可完成连接——请尽量不要直接粘贴到聊天中；我会将其配置到MCP服务器中。

Step 2: Connect the MCP server

步骤2：连接MCP服务器

Once the user has a key, connect the

sonilo

MCP server with it. Prefer the CLI form when the host supports it:

bash

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

For hosts without that CLI (Claude Desktop, Codex), edit the MCP config directly:

Claude Desktop (

claude_desktop_config.json

json

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

Codex (

~/.codex/config.toml

toml

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

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

Both require the

uv

package manager (provides

uvx

) — if not already installed, use

brew install uv

pipx install uv

pip install uv

, or

winget install --id=astral-sh.uv

(see https://docs.astral.sh/uv/getting-started/installation/ for other methods). After editing a config file directly, tell the user to restart the host app (Claude Desktop/Codex) — a

claude mcp add

in Claude Code takes effect on the next session without a restart.

用户获取密钥后，使用该密钥连接

sonilo

MCP服务器。如果主机支持，优先使用CLI形式：

bash

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

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

Claude Desktop（

claude_desktop_config.json

）：

json

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

Codex（

~/.codex/config.toml

）：

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

后，下次会话即可生效，无需重启。

Step 3: Validate

步骤3：验证配置

After connecting, call

get_account_services()

Succeeds: confirm Sonilo is configured and working. Mention
```
get_account_services()
```
also shows what free-trial runs remain per service.
Fails (401): the credential is wrong. On this path that means a bad key — point back to the dashboard link in Step 1 and ask for a corrected one. If the user signed in with
```
sonilo login
```
instead, the key behind that sign-in has expired or been revoked:
```
sonilo login
```
again.
No Sonilo tools appear at all: the MCP server itself isn't connected — re-check Step 2's config location and confirm the host was restarted/reloaded.

连接完成后，调用

get_account_services()

：

成功： 确认Sonilo已配置完成并可正常使用。提及
```
get_account_services()
```
还可显示各服务剩余的免费试用次数。
失败（401错误）： 凭证错误。在此路径下意味着密钥无效——引导用户返回步骤1中的仪表盘链接，获取正确密钥。如果用户通过
```
sonilo login
```
登录，则登录背后的密钥已过期或被撤销：重新运行
```
sonilo login
```
即可。
无Sonilo工具显示： MCP服务器未连接——重新检查步骤2中的配置位置，并确认主机已重启/重载。

Path D: Python/JS SDK or CLI (no MCP)

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

Not every integration goes through an MCP host. If the user is writing code or scripting from a shell:

bash

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

Same API key as Path C — get one from https://platform.sonilo.com/dashboard/api-keys and set it as

SONILO_API_KEY

in the environment (both SDKs and both CLIs read it automatically; no MCP config,

claude mcp add

, or plugin install involved). Validate with the SDK's own account call (

client.account.services()

sonilo.account.services()

) or

sonilo account

on the CLI.

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

bash

pip install sonilo          # Python SDK
npm install sonilo          # JS/TS SDK
pip install sonilo-cli      # Python分发的CLI
npm install -g sonilo-cli   # npm分发的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`命令验证配置。

Optional Configuration (local MCP server)

可选配置（本地MCP服务器）

Mention these only if relevant to what the user is trying to do — they all have sane defaults:

Variable	Default	When to mention it
`SONILO_API_URL`	`https://api.sonilo.com`	Only for a non-default deployment.
`SONILO_MCP_BASE_PATH`	`~/Desktop`	Where generated files are saved by default, and the base for relative input paths. Suggest changing it if the user wants output elsewhere.
`SONILO_MCP_ALLOW_ANY_PATH`	`false`	Set `true` only if the user needs to read/write files outside `SONILO_MCP_BASE_PATH` — explain this widens the tool's file-system access before suggesting it.
`TIME_OUT_SECONDS`	`600`	Raise this if the user hits generation timeouts on long videos — note that `get_sfx_task` / `get_generation_task` (see task-recovery) can always recover a timed-out result regardless of this setting.

仅当与用户操作场景相关时提及以下配置——它们均有合理的默认值：

变量	默认值	提及场景
`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`	如果用户处理长视频时遇到生成超时，可提高此值——注意无论此设置如何， `get_sfx_task` / `get_generation_task` （见任务恢复）始终可恢复超时任务的结果。

Safety Rules

安全规则

Never ask the user to paste an API key, token, or secret directly into chat if a config-file or
```
claude mcp add
```
path is available.
Never print or echo the key's value once configured.
Point users at the dashboard (https://platform.sonilo.com/dashboard/api-keys) to create or rotate keys, and at https://platform.sonilo.com/dashboard/billing for billing/top-up — never fabricate either URL's content.

若存在配置文件或
```
claude mcp add
```
方式，切勿要求用户直接在聊天中粘贴API密钥、令牌或机密信息。
配置完成后，切勿打印或回显密钥值。
引导用户通过仪表盘（https://platform.sonilo.com/dashboard/api-keys）创建或轮换密钥，通过https://platform.sonilo.com/dashboard/billing进行计费/充值——切勿编造上述URL的内容。

setup-api-key

Original

Translation

Sonilo Setup

Sonilo 设置

Step 0: Check what already works (all paths)

步骤0：检查现有可用配置（所有路径通用）

Path A:
`sonilo login`
(no API key, any MCP host)

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

Path B: Remote OAuth plugin (Claude Code only, no API key)

路径B：远程OAuth插件（仅适用于Claude Code，无需API密钥）

Path C: API key (CI, containers, or by preference)

路径C：API密钥（适用于CI、容器，或用户偏好）

Step 1: Get an API key

步骤1：获取API密钥

Step 2: Connect the MCP server

步骤2：连接MCP服务器

Step 3: Validate

步骤3：验证配置

Path D: Python/JS SDK or CLI (no MCP)

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

Optional Configuration (local MCP server)

可选配置（本地MCP服务器）

Safety Rules

安全规则

setup-api-key

Original

Translation

Sonilo Setup

Sonilo 设置

Step 0: Check what already works (all paths)

步骤0：检查现有可用配置（所有路径通用）

Path A: sonilo login (no API key, any MCP host)

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

Path B: Remote OAuth plugin (Claude Code only, no API key)

路径B：远程OAuth插件（仅适用于Claude Code，无需API密钥）

Path C: API key (CI, containers, or by preference)

路径C：API密钥（适用于CI、容器，或用户偏好）

Step 1: Get an API key

步骤1：获取API密钥

Step 2: Connect the MCP server

步骤2：连接MCP服务器

Step 3: Validate

步骤3：验证配置

Path D: Python/JS SDK or CLI (no MCP)

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

Optional Configuration (local MCP server)

可选配置（本地MCP服务器）

Safety Rules

安全规则

Path A:
`sonilo login`
(no API key, any MCP host)

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