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:

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

2. Configure your API Key

Run the following command and enter your API Key when prompted:

Bash
uni auth login

You can also pass the API Key directly. Replace YOUR_API_KEY with your own key:

Bash
uni auth login --api-key YOUR_API_KEY

3. List available models

Bash
uni models list

4. Set a default model

For example, use U2-Flash as the default text model:

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

5. Start chatting

Send a message:

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

For multi-turn conversation, start an interactive session:

Bash
uni text repl
What you want to doCommand
List available modelsuni models list
Configure or check API Key auth statusuni auth login / uni auth status
Send a message / generate textuni text chat
Multi-turn conversationuni text repl
Describe an image or ask about ituni vision describe
Convert text to speechuni speech synthesize
List built-in voicesuni speech voices
Convert audio to textuni asr transcribe
Extract text and information from imagesuni ocr extract
Convert a document to Markdownuni ocr parse
Clone or design a voiceuni voice clone / uni voice design
Upload, list, download, or delete filesuni file upload / list / download / delete
View or change defaultsuni config show / uni config set
Update the tooluni update

Model listing

models list

List models currently available so you can pick a model ID for later calls.

Bash
uni models list

To view results as JSON:

Bash
uni models list --output json

Authentication

auth login

Configure and save an API Key for subsequent commands.

Bash
uni auth login
How to useCommand
Enter API Key when prompteduni auth login
Pass API Key directlyuni 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:

Bash
uni auth status

auth logout

Clear locally saved credentials:

Bash
uni auth logout

Text chat

text chat

Send a message for Q&A, writing, or code generation.

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

Set a system role and stream the reply:

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

You can also pass --message multiple times for multi-turn content:

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

Common options:

OptionDescription
--messageMessage content; can be repeated
--messages-fileRead a messages array from a JSON file or stdin
--toolDefine function/tool calling; repeatable JSON or file path
--modelModel ID; uses the default model if omitted
--systemSystem prompt for role or answer style
--max-tokensMax tokens to generate; default 4096
--temperatureControls randomness of generation
--top-pControls sampling range
--streamStream 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.

Bash
uni text repl --model u2-flash

You can also set a system role at launch:

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

In-session commands are supported. Type / for hints, and press Tab to autocomplete.

Session commandDescription
/exitExit the session
/clearClear conversation history; keep the system prompt
/systemShow the current system prompt
/system You are a writing assistantSet the system prompt
/modelShow the current model
/model u2-flashSwitch model
/save conversation.jsonSave the conversation as JSON
/historyShow current conversation messages
/helpShow 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:

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

Ask about a remote image:

Bash
uni vision describe --image "https://example.com/photo.jpg" --model YOUR_VISION_MODEL_ID --prompt "请描述这张图片中的主要内容"
OptionDescription
--imageLocal image path or image URL; you can also pass the path after the command
--modelModel ID that supports image input; uses the default model if omitted
--promptQuestion you want answered about the image

Speech synthesis

speech voices

List built-in voices, then use a voice ID with --voice:

Bash
uni speech voices

speech synthesize

Convert text to speech using model u2-tts.

Synthesize short text and save audio:

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

Read from a text file and specify a voice:

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

Handle long text:

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

Sync synthesis supports up to 500 characters; for longer text use --async (up to 50,000 characters).

Specify emotion and dialect:

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

Specify word pronunciation:

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

Common options:

OptionDescription
--textText to synthesize
--text-fileRead text from a file; use - to read from stdin
--voiceVoice ID; default cn_male_chenyu
--speed / --volume / --pitch / --brightAdjust speed, volume, pitch, or brightness
--languageLanguage setting
--emotionEmotion setting, e.g. happy
--dialectDialect setting; allowed values: default / sichuan / yueyu
--pronunciationSpecify word pronunciation
--formatAudio output format; default mp3
--sample-rateSample rate; default 32000
--outOutput path; default file name is speech-<timestamp>.<format>
--asyncSynthesize long text asynchronously
--streamStream audio to stdout

Speech recognition

asr transcribe

Convert audio to text using model u2-asr via an async task.

Transcribe a local audio file:

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

Transcribe a publicly accessible audio URL:

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

If the audio URL has no file extension, specify the format explicitly:

Bash
uni asr transcribe --url "https://example.com/audio?id=123" --format wav --language zh --output json
OptionDescription
--fileLocal audio path; mutually exclusive with --url
--urlPublicly accessible audio URL; mutually exclusive with --file
--formatAudio format; required when the URL has no extension
--languageAudio language, e.g. zh for Chinese
--output jsonOutput 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.

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

To specify a model:

Bash
uni ocr extract --file document.png --prompt "提取图片中的文字" --model u2-ocr-med
OptionDescription
--filePath or URL of the image to recognize; max size 10 MB
--promptWhat to extract or recognition requirements
--modelDefault 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:

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

Print the result directly in the terminal:

Bash
uni ocr parse --file slide.png
OptionDescription
--fileLocal document path; supports JPG, PNG, PDF
--outPath to save the Markdown file; if omitted, prints the result
--modelOCR model ID; default u2-ocr
--start-page-idStart page (inclusive)
--end-page-idEnd page (inclusive)

Custom voices

voice clone

Create a custom voice from reference audio:

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

After creation, use the voice for speech synthesis:

Bash
uni speech synthesize --voice my_narrator --text "你好,欢迎收听。" --out narration.mp3
OptionDescription
--audioPath to reference audio
--voice-idCustom voice ID for later synthesis

voice design

Create a voice from a text description:

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

You can also specify a voice ID:

Bash
uni voice design --prompt "低沉男声,纪录片风格" --voice-id my_doc_voice
OptionDescription
--promptDescription of the desired voice characteristics
--voice-idCustom 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:

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

Common purposes:

PurposeDescription
t2a_async_inputSpeech synthesis input file
t2a_asyncSpeech synthesis output file
a2t_async_inputSpeech recognition input file
voice_cloneVoice 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:

Bash
uni file list

Filter by purpose, e.g. audio uploaded for speech recognition:

Bash
uni file list --purpose a2t_async_input

file download

Replace YOUR_FILE_ID with the actual file ID:

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

file delete

Delete a file:

Bash
uni file delete --file-id YOUR_FILE_ID

To specify a purpose explicitly, e.g. delete audio uploaded for speech recognition:

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

If 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:

Bash
uni config show

config set

Set the default model:

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

Set the default output format:

Bash
uni config set --key output --value json

Common config keys:

KeyDescription
default_text_modelDefault model; for image understanding, ensure it supports image input
outputOutput format: text or json
api_styleAPI style: openai (default) or anthropic; persists --style
timeoutRequest timeout
proxyNetwork 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:

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

Global options

These options can be used with CLI commands:

OptionDescription
--api-keyAPI Key for this call; takes precedence over env and local config
--base-urlAPI base URL; default https://maas-api.unisound.com
--styleAPI style: openai (default) or anthropic
--outputResult format: text or json
--timeoutRequest timeout in seconds; default 300
--verbosePrint HTTP request/response details for troubleshooting
--dry-runDry-run mode; do not send real requests
--non-interactiveDisable interactive prompts; for CI/Agent use
--quietReduce non-essential output
--no-colorDisable colored text and loading animations
--helpShow help
--versionShow 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

Bash
uni update

Or update with npm:

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

Get help

Show the command overview:

Bash
uni help

Show options for a specific command:

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

FAQ

I see 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:

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

For image understanding, pass a model that supports image input via --model.

The terminal stops at 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:

Bash
uni text chat --model u2-flash --message '你好!'
Document parsing returns 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:

Bash
uni ocr extract --file document.png --prompt "提取图片中的文字"
Why can't image understanding use the default model?

Image understanding requires a model that supports image input. If the default model is text-only, specify an image-capable model for this command:

Bash
uni vision describe --image photo.jpg --model YOUR_VISION_MODEL_ID
How do I exit an interactive chat?

Type /exit, or press Ctrl+C twice. Pressing Ctrl+C once during a reply only interrupts the current reply.

Where are speech synthesis files saved?

If you omit --out, the file is named speech-<timestamp>.<format>. To choose a path, use --out:

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