Simi Voice CLI

English | 简体中文

Simi Voice CLI 是 Simi Voice API 的官方命令行客户端，适合开发者、自动化脚本、CI 流程，以及需要在终端或宿主环境中生成语音的 agent。

功能特性

• 将文本生成语音
• 自动解析 canonical voice id、slug 或旧版 voice selector
• 在请求发出前，先根据音色 capability 检查 style preset 和输出格式是否可用
• 把音频直接输出到 stdout，方便接入 pipeline
• 按 synthesis job ID 下载音频
• 查看可用音色、能力快照与 synthesis 历史记录
• 提供适合自动化消费的 JSON 输出
• 支持本地配置文件和环境变量两种配置方式

环境要求

• Node.js 20 或更高版本
• 有效的 Simi Voice API key

安装

npm install -g @simi-studio/voice-cli

或者无需全局安装，直接执行：

npx --package @simi-studio/voice-cli simi-voice capabilities --json

快速开始

1. 配置 API 地址和 key

使用环境变量：

export VOICE_API_BASE_URL=https://voice.simi.studio
export VOICE_API_KEY=svk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

或者写入本地配置：

simi-voice config api-url https://voice.simi.studio
simi-voice config api-key svk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. 生成语音

simi-voice generate "你好，来自 Simi Voice" -o hello.mp3

3. 在自动化或 agent 中使用

printf '生成一段欢迎语音。' | simi-voice generate --stdin -o - > welcome.mp3
simi-voice capabilities --json

常用命令

生成语音

simi-voice generate "你好世界"
simi-voice generate "欢迎使用 Simi Voice" -v female-shaonv -o welcome.mp3
simi-voice generate "更快的播放速度" -s 1.5 --pitch 2 --style narration
simi-voice generate "自动化输出" -o hello.mp3 --json
simi-voice generate "自动化输出" -o hello.mp3 --json --quiet
printf '来自 stdin 的文本' | simi-voice generate --stdin -o - > hello.mp3

查看音色

simi-voice voices
simi-voice voices --gender female
simi-voice voices --json

音色响应里会包含 capability snapshot，方便宿主动态发现支持的格式、控制项和 style preset。

查看 synthesis 历史记录

simi-voice history
simi-voice history --limit 5
simi-voice history --json

下载音频

simi-voice download <synthesis-job-id>
simi-voice download <synthesis-job-id> -o my-audio.mp3
simi-voice download <synthesis-job-id> -o - > my-audio.mp3
simi-voice download <synthesis-job-id> --json

查看配置

simi-voice config
simi-voice config --json
simi-voice config api-url https://voice.simi.studio --json

配置说明

CLI 按以下优先级读取配置：

1. 环境变量
2. ~/.config/simi-voice/config.json

环境变量优先于本地配置文件。

| 变量 | 说明 | 默认值 | | --- | --- | --- | | VOICE_API_BASE_URL | Voice API 地址 | http://localhost:4000 | | VOICE_API_KEY | 用于鉴权的访问密钥 | 无 |

自动化契约

• --json：把结构化结果写到 stdout
• --quiet：抑制非必要进度输出
• 进度和错误信息写入 stderr
• generate --stdin：从 stdin 读取文本
• generate -o - 与 download -o -：把音频写到 stdout
• capabilities --json：返回适合宿主自动发现能力的 JSON 描述

退出码

| 退出码 | 含义 | | --- | --- | | 0 | 成功 | | 2 | 参数或用法错误 | | 3 | 配置缺失或本地构建产物缺失 | | 4 | 鉴权或权限错误 | | 5 | 远端 API 错误 | | 10 | 网络或传输错误 |

故障排查

VOICE_API_KEY is not set

在 shell 中设置 VOICE_API_KEY，或执行：

simi-voice config api-key <your-api-key>

CLI build output is missing

如果你是从源码仓库本地运行，而不是从 npm 安装：

pnpm install
pnpm build

开发

pnpm install
pnpm test
pnpm typecheck
pnpm build