uni CLI 工具 | 文档中心

快速开始

1. 安装并验证

使用前，请先安装 Node.js 18 或更高版本，并准备好云知声 MaaS 平台的 API Key。

在终端中执行：

Bash

npm install -g @unisound/u2-cli
uni --version

运行以下命令，按提示输入 API Key：

Bash

uni auth login

也可以直接指定 API Key。请将示例中的 YOUR_API_KEY 替换为自己的密钥：

Bash

uni auth login --api-key YOUR_API_KEY

3. 查询可用模型

Bash

uni models list

4. 设置默认模型

例如，使用 U2 Flash 作为默认文本模型：

Bash

uni config set --key default_text_model --value u2-flash

5. 开始对话

发送一条消息：

Bash

uni text chat --message "用一句话介绍云知声 MaaS 平台"

如需连续对话，启动交互式会话：

Bash

uni text repl

文本对话和图片理解均需要指定模型。未传入 --model 时，会使用 default_text_model；两者都未设置时会提示 No model specified。图片理解请另行指定支持图片输入的模型。

功能导航

你想做什么	使用命令
查询可用模型	`uni models list`
配置或查看 API Key 认证状态	`uni auth login` / `uni auth status`
发送消息、生成文本	`uni text chat`
连续多轮对话	`uni text repl`
描述图片、针对图片提问	`uni vision describe`
将文字转换为语音	`uni speech synthesize`
查看内置音色	`uni speech voices`
将音频转换为文字	`uni asr transcribe`
提取图片中的文字和信息	`uni ocr extract`
将文档转换为 Markdown	`uni ocr parse`
克隆或设计音色	`uni voice clone` / `uni voice design`
上传、查看、下载或删除文件	`uni file upload` / `list` / `download` / `delete`
查看或修改默认设置	`uni config show` / `uni config set`
更新工具	`uni update`

模型查询

models list

查看当前可用的模型，以便在后续调用中选择模型 ID。

Bash

uni models list

如需以 JSON 格式查看结果：

Bash

uni models list --output json

认证管理

配置并保存 API Key，供后续命令使用。

Bash

uni auth login

使用方式	命令
按提示输入 API Key	`uni auth login`
直接指定 API Key	`uni auth login --api-key YOUR_API_KEY`

API Key 保存在本机的 ~/.uni/config.json 中，也可通过环境变量 UNI_API_KEY 提供。使用优先级为：命令行 --api-key → 环境变量 UNI_API_KEY → 本地配置文件。

auth status

查看当前认证状态：

Bash

uni auth status

auth logout

清除本地已保存的凭证：

Bash

uni auth logout

如果另外设置了 UNI_API_KEY 环境变量，需同时移除该变量，才能停止使用其中的密钥。

文本对话

text chat

发送消息，进行问答、写作或代码生成。

Bash

uni text chat --model u2-flash --message "帮我写一段简洁的产品介绍"

设置助手角色，并逐步显示回复：

Bash

uni text chat --model u2-flash --system "你是一位写作助手" --message "将这句话改得更简洁：我们致力于为用户提供便捷高效的服务。" --stream

也可以通过重复传入 --message 提供多轮对话内容：

Bash

uni text chat --model u2-flash --message "你好" --message "assistant:你好，有什么可以帮助你？" --message "请介绍一下你能做什么"

常用参数：

参数	说明
`--message`	消息内容；可重复传入
`--messages-file`	从 JSON 文件或标准输入读取消息数组
`--tool`	定义 function/tool calling；可重复传入 JSON 或文件路径
`--model`	模型 ID；未指定时使用默认模型
`--system`	系统提示词，用于设定助手角色或回答要求
`--max-tokens`	最大生成 Token 数，默认 `4096`
`--temperature`	调整生成内容的随机性
`--top-p`	调整生成内容的采样范围
`--stream`	逐步输出回复内容；TTY 下默认开启，管道/脚本下默认关闭

text repl

进入交互式多轮会话。启动后，直接输入问题即可继续对话。

Bash

uni text repl --model u2-flash

也可以在启动时设置助手角色：

Bash

uni text repl --model u2-flash --system "你是一位编程助手" --temperature 0.7

会话内支持以下命令。输入 / 可查看提示，按 Tab 可补全。

会话命令	说明
`/exit`	退出会话
`/clear`	清空对话历史，保留系统提示词
`/system`	查看当前系统提示词
`/system 你是一位写作助手`	设置系统提示词
`/model`	查看当前模型
`/model u2-flash`	切换模型
`/save conversation.json`	将对话保存为 JSON 文件
`/history`	查看当前对话消息
`/help`	显示会话帮助

回复过程中按 Ctrl+C 只会中断当前回复；连按两次 Ctrl+C 可退出会话。Ctrl+D 不能退出此会话，请使用 /exit。

图片理解

vision describe

描述图片内容，或针对图片提问。支持本地图片和远程图片 URL。

将 YOUR_VISION_MODEL_ID 替换为支持图片输入的模型 ID：

Bash

uni vision describe --image photo.jpg --model YOUR_VISION_MODEL_ID

针对远程图片提问：

Bash

uni vision describe --image "https://example.com/photo.jpg" --model YOUR_VISION_MODEL_ID --prompt "请描述这张图片中的主要内容"

参数	说明
`--image`	本地图片路径或图片 URL；也可直接在命令后提供图片路径
`--model`	支持图片输入的模型 ID；未指定时读取默认模型
`--prompt`	希望模型针对图片回答的问题

语音合成

speech voices

查看内置音色，选择后将音色 ID 用于 --voice：

Bash

uni speech voices

speech synthesize

将文字转换为语音，使用模型 u2-tts。

合成短文本并保存音频：

Bash

uni speech synthesize --text "你好，欢迎使用云知声。" --out welcome.mp3

读取文本文件并指定音色：

Bash

uni speech synthesize --text-file narration.txt --voice cn_female_jiajia --out narration.mp3

处理长文本：

Bash

uni speech synthesize --text-file long.txt --async --out narration.mp3

同步合成支持不超过 500 字的文本；长文本可使用 --async，支持不超过 50,000 字。

指定情感和方言：

Bash

uni speech synthesize --text "你好" --voice cn_male_chenyu --emotion happy --dialect sichuan

指定词语读音：

Bash

uni speech synthesize --text "重塑美好生活" --pronunciation "重塑/重chóng塑"

常用参数：

参数	说明
`--text`	待合成的文本
`--text-file`	从文件读取文本；使用 `-` 可从标准输入读取
`--voice`	音色 ID，默认 `cn_male_chenyu`
`--speed` / `--volume` / `--pitch` / `--bright`	调整语速、音量、音调或明亮度
`--language`	语言设置
`--emotion`	情感设置，例如 `happy`
`--dialect`	方言设置，合法值：`default` / `sichuan` / `yueyu`
`--pronunciation`	指定词语读音
`--format`	音频输出格式，默认 `mp3`
`--sample-rate`	采样率，默认 `32000`
`--out`	音频保存路径；默认文件名为 `speech-<时间戳>.<格式>`
`--async`	使用异步方式合成长文本
`--stream`	将流式音频输出到标准输出

语音识别

asr transcribe

将音频转换为文字，使用模型 u2-asr，通过异步任务处理。

转写本地音频：

Bash

uni asr transcribe --file meeting.mp3 --language zh

转写公网可访问的音频：

Bash

uni asr transcribe --url "https://example.com/meeting.mp3" --language zh

如果音频 URL 不包含文件扩展名，请显式指定格式：

Bash

uni asr transcribe --url "https://example.com/audio?id=123" --format wav --language zh --output json

参数	说明
`--file`	本地音频路径；与 `--url` 二选一
`--url`	公网可访问的音频 URL；与 `--file` 二选一
`--format`	音频格式；URL 不含扩展名时需要指定
`--language`	音频语言，例如中文使用 `zh`
`--output json`	以 JSON 格式输出结果

支持音频格式：mp3、wav、opus、amr、m4a、ogg。

OCR 文字识别与文档解析

ocr extract

从图片中提取文字或指定信息，例如票据金额、日期或图表标签。

Bash

uni ocr extract --file receipt.jpg --prompt "提取总金额和日期"

如需指定模型：

Bash

uni ocr extract --file document.png --prompt "提取图片中的文字" --model u1-ocr-med

参数	说明
`--file`	待识别的图片路径或 URL，图片大小不超过 10 MB
`--prompt`	希望提取的内容或识别要求
`--model`	默认 `u1-ocr`，也支持 `u1-ocr-med`

ocr parse

将 JPG、PNG 或 PDF 文档转换为 Markdown，通过异步任务处理。

解析文档并保存结果：

Bash

uni ocr parse --file contract.pdf --out contract.md

直接在终端查看解析结果：

Bash

uni ocr parse --file slide.png

参数	说明
`--file`	本地文档路径，支持 JPG、PNG、PDF
`--out`	Markdown 文件的保存路径；不指定时直接输出结果
`--model`	OCR 模型 ID，默认 `u1-ocr`
`--start-page-id`	起始页（含）
`--end-page-id`	结束页（含）

自定义音色

voice clone

使用参考音频创建自定义音色：

Bash

uni voice clone --audio speaker.wav --voice-id my_narrator

创建成功后，可将该音色用于语音合成：

Bash

uni speech synthesize --voice my_narrator --text "你好，欢迎收听。" --out narration.mp3

参数	说明
`--audio`	参考音频路径
`--voice-id`	自定义音色 ID，用于后续合成

voice design

通过文字描述创建音色：

Bash

uni voice design --prompt "温柔的中年女声，适合讲故事"

也可以指定音色 ID：

Bash

uni voice design --prompt "低沉男声，纪录片风格" --voice-id my_doc_voice

参数	说明
`--prompt`	希望生成的音色特征描述
`--voice-id`	自定义音色 ID，可选

使用设计音色合成语音时，需要指定模型 u2-tts-design，并使用创建成功后的音色 ID。

文件管理

管理通过 CLI 上传的文件。文件 ID 可通过上传结果或文件列表获取。

file upload

上传文件时，需要通过 --purpose 指定用途。例如，上传语音合成所用的文本文件：

Bash

uni file upload --file narration.txt --purpose t2a_async_input

常用文件用途：

用途值	说明
`t2a_async_input`	语音合成输入文件
`t2a_async`	语音合成输出文件
`a2t_async_input`	语音识别输入文件
`voice_clone`	音色克隆参考文件

解析本地文档可直接使用 uni ocr parse --file contract.pdf，无需手动指定上传用途。

file list

查看已上传的文件：

Bash

uni file list

按用途筛选，例如查看语音识别上传的音频：

Bash

uni file list --purpose a2t_async_input

file download

将 YOUR_FILE_ID 替换为实际文件 ID：

Bash

uni file download --file-id YOUR_FILE_ID --out audio.mp3

file delete

删除指定文件：

Bash

uni file delete --file-id YOUR_FILE_ID

如需明确指定用途，例如删除语音识别上传的音频：

Bash

uni file delete --file-id YOUR_FILE_ID --purpose a2t_async_input

下载或删除时，如省略 --purpose，工具会自动从文件列表中查找对应用途。

配置与通用参数

config show

查看当前配置：

Bash

uni config show

config set

设置默认模型：

Bash

uni config set --key default_text_model --value u2-flash

设置默认输出格式：

Bash

uni config set --key output --value json

常用配置项：

配置项	说明
`default_text_model`	默认模型；图片理解使用时须确认该模型支持图片输入
`output`	输出格式：`text` 或 `json`
`api_style`	API 协议风格：`openai`（默认）或 `anthropic`，对应 `--style`
`timeout`	请求超时时间
`proxy`	网络代理地址

config export-schema

将 CLI 命令导出为 Anthropic/OpenAI 兼容的 JSON tool schema，便于 Agent 集成调用。

例如导出 text chat 的 tool schema：

Bash

uni config export-schema --command "text chat"

通用参数

以下参数可用于命令行调用：

参数	说明
`--api-key`	指定本次调用使用的 API Key，优先于环境变量和本地配置
`--base-url`	API 地址，默认 `https://maas-api.unisound.com`
`--style`	协议风格：`openai`（默认）或 `anthropic`
`--output`	结果输出格式：`text` 或 `json`
`--timeout`	请求超时时间，单位为秒，默认 `300`
`--verbose`	打印 HTTP 请求/响应详情，便于排障
`--dry-run`	预演模式，不发送真实请求
`--non-interactive`	禁用交互提示，适用于 CI/Agent 场景
`--quiet`	减少非必要输出
`--no-color`	关闭彩色文字和加载动画
`--help`	查看帮助
`--version`	查看当前版本

--output 控制命令结果的展示格式；语音命令中的 --format 控制音频格式，两者用途不同。

如需通过环境变量设置，可使用 UNI_API_KEY 提供密钥，或使用 UNI_OUTPUT 指定 text / json 输出格式。

更新与帮助

更新到最新版本

Bash

uni update

也可以使用 npm 更新：

Bash

npm install -g @unisound/u2-cli@latest

查看帮助

查看命令总览：

Bash

uni help

查看具体命令的参数：

Bash

uni text chat --help
uni speech synthesize --help
uni ocr parse --help

常见问题

提示 No model specified，怎么办？

text chat、text repl 和 vision describe 需要指定模型。可以在命令中传入 --model，或先设置默认模型：

Bash

uni models list
uni config set --key default_text_model --value u2-flash

图片理解请通过 --model 指定支持图片输入的模型。

终端停在 dquote>，命令没有执行，怎么办？

这通常表示双引号尚未闭合。按 Ctrl+C 取消当前输入，检查引号是否成对，再重新执行。

在 zsh 中，如果消息包含 !，可使用单引号包裹消息，避免触发历史展开：

Bash

uni text chat --model u2-flash --message '你好!'

文档解析提示 invalid file purpose (code 100001)，怎么办？

当前服务可能尚未支持所需的文件上传用途或文档解析能力。请联系平台支持确认该能力是否可用。如果只需要提取图片中的信息，可以使用：

Bash

uni ocr extract --file document.png --prompt "提取图片中的文字"

为什么图片理解不能使用默认模型？

图片理解要求模型支持图片输入。如果默认模型只支持文本，请为本次命令指定支持图片输入的模型：

Bash

uni vision describe --image photo.jpg --model YOUR_VISION_MODEL_ID

如何退出交互式对话？

输入 /exit，或连按两次 Ctrl+C。回复过程中按一次 Ctrl+C 只会中断当前回复。

语音合成文件保存在哪里？

未指定 --out 时，生成的文件名为 speech-<时间戳>.<格式>。如需明确保存位置，请使用 --out 指定路径：

Bash

uni speech synthesize --text "你好" --out welcome.mp3

快速开始

1. 安装并验证

2. 配置 API Key

3. 查询可用模型

4. 设置默认模型

5. 开始对话

功能导航

模型查询

models list

认证管理

auth login

auth status

auth logout

文本对话

text chat

text repl

图片理解

vision describe

语音合成

speech voices

speech synthesize

语音识别

asr transcribe

OCR 文字识别与文档解析

ocr extract

ocr parse

自定义音色

voice clone

voice design

文件管理

file upload

file list

file download

file delete

配置与通用参数

config show

config set

config export-schema

通用参数

更新与帮助

更新到最新版本

查看帮助

常见问题