uni CLI Tool
uni CLI is the command-line tool for the Unisound MaaS platform. From your terminal you can list available models, run text chat, image understanding, speech synthesis, speech recognition, and OCR document processing, as well as create custom voices and manage uploaded files.
Quick start
1. Install and verify
Before you begin, install Node.js 18 or later and prepare an API Key from the Unisound MaaS platform.
Run in your terminal:
npm install -g @unisound/u2-cli
uni --version2. Configure your API Key
Run the following command and enter your API Key when prompted:
uni auth loginYou can also pass the API Key directly. Replace YOUR_API_KEY with your own key:
uni auth login --api-key YOUR_API_KEY3. List available models
uni models list4. Set a default model
For example, use U2-Flash as the default text model:
uni config set --key default_text_model --value u2-flash5. Start chatting
Send a message:
uni text chat --message "用一句话介绍云知声 MaaS 平台"For multi-turn conversation, start an interactive session:
uni text replFeature map
| What you want to do | Command |
|---|---|
| List available models | uni models list |
| Configure or check API Key auth status | uni auth login / uni auth status |
| Send a message / generate text | uni text chat |
| Multi-turn conversation | uni text repl |
| Describe an image or ask about it | uni vision describe |
| Convert text to speech | uni speech synthesize |
| List built-in voices | uni speech voices |
| Convert audio to text | uni asr transcribe |
| Extract text and information from images | uni ocr extract |
| Convert a document to Markdown | uni ocr parse |
| Clone or design a voice | uni voice clone / uni voice design |
| Upload, list, download, or delete files | uni file upload / list / download / delete |
| View or change defaults | uni config show / uni config set |
| Update the tool | uni update |
Model listing
models list
List models currently available so you can pick a model ID for later calls.
uni models listTo view results as JSON:
uni models list --output jsonAuthentication
auth login
Configure and save an API Key for subsequent commands.
uni auth login| How to use | Command |
|---|---|
| Enter API Key when prompted | uni auth login |
| Pass API Key directly | uni auth login --api-key YOUR_API_KEY |
The API Key is stored in ~/.uni/config.json on your machine, or you can provide it via the UNI_API_KEY environment variable. Precedence: CLI --api-key → env UNI_API_KEY → local config file.
auth status
Check the current auth status:
uni auth statusauth logout
Clear locally saved credentials:
uni auth logoutText chat
text chat
Send a message for Q&A, writing, or code generation.
uni text chat --model u2-flash --message "帮我写一段简洁的产品介绍"Set a system role and stream the reply:
uni text chat --model u2-flash --system "你是一位写作助手" --message "将这句话改得更简洁:我们致力于为用户提供便捷高效的服务。" --streamYou can also pass --message multiple times for multi-turn content:
uni text chat --model u2-flash --message "你好" --message "assistant:你好,有什么可以帮助你?" --message "请介绍一下你能做什么"Common options:
| Option | Description |
|---|---|
--message | Message content; can be repeated |
--messages-file | Read a messages array from a JSON file or stdin |
--tool | Define function/tool calling; repeatable JSON or file path |
--model | Model ID; uses the default model if omitted |
--system | System prompt for role or answer style |
--max-tokens | Max tokens to generate; default 4096 |
--temperature | Controls randomness of generation |
--top-p | Controls sampling range |
--stream | Stream the reply gradually; default on in TTY, default off when piped/scripted |
text repl
Enter an interactive multi-turn session. After it starts, type questions to continue the conversation.
uni text repl --model u2-flashYou can also set a system role at launch:
uni text repl --model u2-flash --system "你是一位编程助手" --temperature 0.7In-session commands are supported. Type / for hints, and press Tab to autocomplete.
| Session command | Description |
|---|---|
/exit | Exit the session |
/clear | Clear conversation history; keep the system prompt |
/system | Show the current system prompt |
/system You are a writing assistant | Set the system prompt |
/model | Show the current model |
/model u2-flash | Switch model |
/save conversation.json | Save the conversation as JSON |
/history | Show current conversation messages |
/help | Show session help |
Image understanding
vision describe
Describe an image or ask questions about it. Supports local images and remote image URLs.
Replace YOUR_VISION_MODEL_ID with a model ID that supports image input:
uni vision describe --image photo.jpg --model YOUR_VISION_MODEL_IDAsk about a remote image:
uni vision describe --image "https://example.com/photo.jpg" --model YOUR_VISION_MODEL_ID --prompt "请描述这张图片中的主要内容"| Option | Description |
|---|---|
--image | Local image path or image URL; you can also pass the path after the command |
--model | Model ID that supports image input; uses the default model if omitted |
--prompt | Question you want answered about the image |
Speech synthesis
speech voices
List built-in voices, then use a voice ID with --voice:
uni speech voicesspeech synthesize
Convert text to speech using model u2-tts.
Synthesize short text and save audio:
uni speech synthesize --text "你好,欢迎使用云知声。" --out welcome.mp3Read from a text file and specify a voice:
uni speech synthesize --text-file narration.txt --voice cn_female_jiajia --out narration.mp3Handle long text:
uni speech synthesize --text-file long.txt --async --out narration.mp3Sync synthesis supports up to 500 characters; for longer text use --async (up to 50,000 characters).
Specify emotion and dialect:
uni speech synthesize --text "你好" --voice cn_male_chenyu --emotion happy --dialect sichuanSpecify word pronunciation:
uni speech synthesize --text "重塑美好生活" --pronunciation "重塑/重chóng塑"Common options:
| Option | Description |
|---|---|
--text | Text to synthesize |
--text-file | Read text from a file; use - to read from stdin |
--voice | Voice ID; default cn_male_chenyu |
--speed / --volume / --pitch / --bright | Adjust speed, volume, pitch, or brightness |
--language | Language setting |
--emotion | Emotion setting, e.g. happy |
--dialect | Dialect setting; allowed values: default / sichuan / yueyu |
--pronunciation | Specify word pronunciation |
--format | Audio output format; default mp3 |
--sample-rate | Sample rate; default 32000 |
--out | Output path; default file name is speech-<timestamp>.<format> |
--async | Synthesize long text asynchronously |
--stream | Stream audio to stdout |
Speech recognition
asr transcribe
Convert audio to text using model u2-asr via an async task.
Transcribe a local audio file:
uni asr transcribe --file meeting.mp3 --language zhTranscribe a publicly accessible audio URL:
uni asr transcribe --url "https://example.com/meeting.mp3" --language zhIf the audio URL has no file extension, specify the format explicitly:
uni asr transcribe --url "https://example.com/audio?id=123" --format wav --language zh --output json| Option | Description |
|---|---|
--file | Local audio path; mutually exclusive with --url |
--url | Publicly accessible audio URL; mutually exclusive with --file |
--format | Audio format; required when the URL has no extension |
--language | Audio language, e.g. zh for Chinese |
--output json | Output results as JSON |
Supported audio formats: mp3, wav, opus, amr, m4a, ogg.
OCR and document parsing
ocr extract
Extract text or specific information from an image, such as receipt totals, dates, or chart labels.
uni ocr extract --file receipt.jpg --prompt "提取总金额和日期"To specify a model:
uni ocr extract --file document.png --prompt "提取图片中的文字" --model u2-ocr-med| Option | Description |
|---|---|
--file | Path or URL of the image to recognize; max size 10 MB |
--prompt | What to extract or recognition requirements |
--model | Default u2-ocr; also supports u2-ocr-med |
ocr parse
Convert JPG, PNG, or PDF documents to Markdown via an async task.
Parse a document and save the result:
uni ocr parse --file contract.pdf --out contract.mdPrint the result directly in the terminal:
uni ocr parse --file slide.png| Option | Description |
|---|---|
--file | Local document path; supports JPG, PNG, PDF |
--out | Path to save the Markdown file; if omitted, prints the result |
--model | OCR model ID; default u2-ocr |
--start-page-id | Start page (inclusive) |
--end-page-id | End page (inclusive) |
Custom voices
voice clone
Create a custom voice from reference audio:
uni voice clone --audio speaker.wav --voice-id my_narratorAfter creation, use the voice for speech synthesis:
uni speech synthesize --voice my_narrator --text "你好,欢迎收听。" --out narration.mp3| Option | Description |
|---|---|
--audio | Path to reference audio |
--voice-id | Custom voice ID for later synthesis |
voice design
Create a voice from a text description:
uni voice design --prompt "温柔的中年女声,适合讲故事"You can also specify a voice ID:
uni voice design --prompt "低沉男声,纪录片风格" --voice-id my_doc_voice| Option | Description |
|---|---|
--prompt | Description of the desired voice characteristics |
--voice-id | Custom voice ID; optional |
File management
Manage files uploaded via the CLI. File IDs come from upload results or the file list.
file upload
When uploading, set the purpose with --purpose. For example, upload a text file for speech synthesis:
uni file upload --file narration.txt --purpose t2a_async_inputCommon purposes:
| Purpose | Description |
|---|---|
t2a_async_input | Speech synthesis input file |
t2a_async | Speech synthesis output file |
a2t_async_input | Speech recognition input file |
voice_clone | Voice clone reference file |
To parse a local document, use uni ocr parse --file contract.pdf directly—no need to set an upload purpose manually.
file list
List uploaded files:
uni file listFilter by purpose, e.g. audio uploaded for speech recognition:
uni file list --purpose a2t_async_inputfile download
Replace YOUR_FILE_ID with the actual file ID:
uni file download --file-id YOUR_FILE_ID --out audio.mp3file delete
Delete a file:
uni file delete --file-id YOUR_FILE_IDTo specify a purpose explicitly, e.g. delete audio uploaded for speech recognition:
uni file delete --file-id YOUR_FILE_ID --purpose a2t_async_inputIf you omit --purpose for download or delete, the tool looks up the matching purpose from the file list.
Configuration and global options
config show
Show the current configuration:
uni config showconfig set
Set the default model:
uni config set --key default_text_model --value u2-flashSet the default output format:
uni config set --key output --value jsonCommon config keys:
| Key | Description |
|---|---|
default_text_model | Default model; for image understanding, ensure it supports image input |
output | Output format: text or json |
api_style | API style: openai (default) or anthropic; persists --style |
timeout | Request timeout |
proxy | Network proxy address |
config export-schema
Export CLI command(s) as Anthropic/OpenAI-compatible JSON tool schemas for Agent integration.
For example, export the tool schema for text chat:
uni config export-schema --command "text chat"Global options
These options can be used with CLI commands:
| Option | Description |
|---|---|
--api-key | API Key for this call; takes precedence over env and local config |
--base-url | API base URL; default https://maas-api.unisound.com |
--style | API style: openai (default) or anthropic |
--output | Result format: text or json |
--timeout | Request timeout in seconds; default 300 |
--verbose | Print HTTP request/response details for troubleshooting |
--dry-run | Dry-run mode; do not send real requests |
--non-interactive | Disable interactive prompts; for CI/Agent use |
--quiet | Reduce non-essential output |
--no-color | Disable colored text and loading animations |
--help | Show help |
--version | Show the current version |
You can also set UNI_API_KEY for the key, or UNI_OUTPUT to text / json for the output format.
Updates and help
Update to the latest version
uni updateOr update with npm:
npm install -g @unisound/u2-cli@latestGet help
Show the command overview:
uni helpShow options for a specific command:
uni text chat --help
uni speech synthesize --help
uni ocr parse --helpFAQ
No model specified. What should I do?text chat, text repl, and vision describe require a model. Pass --model on the command, or set a default model first:
uni models list
uni config set --key default_text_model --value u2-flashFor image understanding, pass a model that supports image input via --model.
dquote> and the command does not run. What should I do?This usually means a double quote is still open. Press Ctrl+C to cancel, check that quotes are paired, then run the command again.
In zsh, if the message contains !, wrap it in single quotes to avoid history expansion:
uni text chat --model u2-flash --message '你好!'invalid file purpose (code 100001). What should I do?The service may not yet support the required upload purpose or document parsing capability. Contact platform support to confirm availability. If you only need to extract information from an image, use:
uni ocr extract --file document.png --prompt "提取图片中的文字"Image understanding requires a model that supports image input. If the default model is text-only, specify an image-capable model for this command:
uni vision describe --image photo.jpg --model YOUR_VISION_MODEL_IDType /exit, or press Ctrl+C twice. Pressing Ctrl+C once during a reply only interrupts the current reply.
If you omit --out, the file is named speech-<timestamp>.<format>. To choose a path, use --out:
uni speech synthesize --text "你好" --out welcome.mp3