### Install OpenClaw (Recommended Script)

Source: https://maas.unisound.com/docs/toolAI/openclaw

Installs OpenClaw using the recommended installation script for macOS and Linux. Ensure Node.js 22+ is installed first.

```Bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

--------------------------------

### Configure OpenClaw

Source: https://maas.unisound.com/docs/toolAI/openclaw

Starts the OpenClaw configuration process. This command guides you through setting up the model and API details.

```Bash
npx openclaw configure
```

--------------------------------

### Install OpenAI SDK

Source: https://maas.unisound.com/docs/token-plan/quickstart

Install the OpenAI Python SDK to interact with the API. This is a prerequisite for making API calls.

```python
pip install openai
```

--------------------------------

### Verify OpenCode Installation

Source: https://maas.unisound.com/docs/toolAI/opencode

Verify the OpenCode installation by running the version command in the terminal. A version number indicates a successful installation.

```Bash
opencode -v
```

--------------------------------

### Python Text Generation Example

Source: https://maas.unisound.com/docs/guide/text/text-generation

This snippet demonstrates how to use the OpenAI SDK with the Maas API for text generation. Ensure you have the 'openai' package installed.

```Python
# Install OpenAI SDK first: `pip install openai`
from openai import OpenAI

client = OpenAI(
    base_url="https://maas-api.hivoice.cn/v1",
    api_key="<API_KEY>",
)

response = client.chat.completions.create(
    model="u2",
    messages=[
        {"role": "user", "content": "Hi"},
    ],
)

print(response.choices[0].message.content)

```

--------------------------------

### Install OpenCode CLI

Source: https://maas.unisound.com/docs/toolAI/opencode

Install the OpenCode AI package globally using npm. Ensure Node.js v18.0 or later is installed.

```Bash
npm install -g opencode-ai
```

--------------------------------

### Connect and Send Audio Example (wscat)

Source: https://maas.unisound.com/docs/api/transcribe/realtime

This example demonstrates how to connect to the real-time transcription service using wscat and send initial configuration and audio data.

```shell
# Connect (wscat example)
wscat -c "wss://maas-api.hivoice.cn/v1/audio/asr/realtime?model=u2-asr" \
  -H "Authorization: Bearer <api_key>"

# Text frame: start
{
  "type": "start",
  "data": {
    "format": "opus",
    "sample": "16k",
    "variable": "true",
    "punctuation": "true",
    "post_proc": "true",
    "max_end_silence": "500",
    "context": "Product name is XiaoYun Assistant",
    "hotwords": ["XiaoYun","ASR"]
  }
}

# Binary frames: encoded audio chunks (not Base64)

# Text frame: end
{ "type": "end" }
```

--------------------------------

### Install OpenClaw (npm)

Source: https://maas.unisound.com/docs/toolAI/openclaw

Installs OpenClaw globally using npm. This is an alternative installation method for macOS and Linux.

```Bash
npm install -g openclaw@latest
```

--------------------------------

### Install Kilo Code CLI

Source: https://maas.unisound.com/docs/toolAI/kilo-code

Install the Kilo Code CLI using npm. Ensure Node.js 18 or later is installed first.

```Shell
npm install -g @kilocode/cli
```

--------------------------------

### List Files Response Example

Source: https://maas.unisound.com/docs/api/file-management/list

This is an example of a successful response when listing files. It includes the total number of files matching the query and an array of file objects, each containing details like file_id, bytes, created_at, filename, and purpose. The base_resp object indicates the success status.

```json
{
  "total": 2,
  "files": [
    {
      "file_id": 871009177767936,
      "bytes": 213836,
      "created_at": 1774268796,
      "filename": "test.wav",
      "purpose": "voice_clone"
    },
    {
      "file_id": 871009177767937,
      "bytes": 259325,
      "created_at": 1774268796,
      "filename": "test.jpg",
      "purpose": "ocr_async_input"
    }
  ],
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

--------------------------------

### Install Hermes Agent

Source: https://maas.unisound.com/docs/toolAI/hermes-agent

Use this command to install the Hermes Agent on Linux or macOS. For Windows, ensure WSL2 is installed first.

```Bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

--------------------------------

### Start Kilo Code CLI

Source: https://maas.unisound.com/docs/toolAI/kilo-code

Start the Kilo Code CLI after completing the configuration. You can then switch models and use the Unisound U2 model.

```Shell
kilocode
```

--------------------------------

### Start OpenCode CLI

Source: https://maas.unisound.com/docs/toolAI/opencode

Run the OpenCode command in your terminal after completing the configuration. You can then use '/models' to view and switch models.

```Bash
opencode
```

--------------------------------

### Install OpenClaw (Windows PowerShell)

Source: https://maas.unisound.com/docs/toolAI/openclaw

Installs OpenClaw on Windows using PowerShell. This script handles the installation process for the Windows environment.

```PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex
```

--------------------------------

### Text Generation Usage Example

Source: https://maas.unisound.com/docs/guide/text/text-generation

This example demonstrates how to use the Text Generation API with the OpenAI SDK. It shows how to set up the client with a custom base URL and API key, and how to make a chat completion request.

```APIDOC
## Text Generation API Usage

This section provides an example of how to interact with the Text Generation API using Python and the OpenAI SDK.

### Description

This example demonstrates how to configure the OpenAI client to use the Maas API endpoint for text generation. It includes setting the `base_url` and `api_key`, and making a sample chat completion request.

### Method

POST

### Endpoint

`/v1/chat/completions`

### Parameters

#### Request Body

- **model** (string) - Required - The name of the model to use (e.g., "u2", "u1-insuremed").
- **messages** (array) - Required - A list of message objects representing the conversation history.
  - **role** (string) - Required - The role of the author of the message (e.g., "user", "assistant").
  - **content** (string) - Required - The content of the message.

### Request Example

```python
# Install OpenAI SDK first: `pip install openai`
from openai import OpenAI

client = OpenAI(
    base_url="https://maas-api.hivoice.cn/v1",
    api_key="<API_KEY>",
)

response = client.chat.completions.create(
    model="u2",
    messages=[
        {"role": "user", "content": "Hi"},
    ],
)

print(response.choices[0].message.content)
```

### Response

#### Success Response (200)

- **choices** (array) - A list of choices, where each choice contains a message.
  - **message** (object)
    - **content** (string) - The generated text content.

#### Response Example

```json
{
  "choices": [
    {
      "message": {
        "content": "Hello! How can I help you today?"
      }
    }
  ]
}
```
```

--------------------------------

### Connect and Transcribe

Source: https://maas.unisound.com/docs/api/transcribe/oneshot

This snippet demonstrates how to connect to the One-Shot Speech Recognition API using WebSockets and send audio data for transcription. It includes examples of the 'start' and 'end' text frames, as well as the expected binary audio frames.

```APIDOC
## Connect and Transcribe

### Description
Connect to the WebSocket endpoint to initiate a speech recognition session. Send a 'start' frame with session parameters, followed by binary audio frames, and finally an 'end' frame to signal the completion of the audio stream.

### Method
WebSocket Connection

### Endpoint
`wss://maas-api.hivoice.cn/v1/ws/asr/oneshot`

### Parameters
#### Query Parameters
- **model** (string) - Required - The ASR model to use (e.g., `u2-asr`).
- **trace_id** (string) - Required - A unique identifier for the trace.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer <api_key>`).

### Request Frame Examples

#### Start Frame
```json
{
  "type": "start",
  "request_id": "trace-abc-001",
  "format": "opus",
  "sample": "16k",
  "variable": "true",
  "punctuation": "true",
  "post_proc": "true",
  "server_vad": "false",
  "context": "Customer service call",
  "hotwords": ["Unisound"]
}
```

#### Binary Audio Frames
(Encoded audio chunks in the specified format, e.g., Opus)

#### End Frame
```json
{
  "type": "end"
}
```

### Response Examples

#### Result Frame (Variable)
```json
{
  "code": 0,
  "msg": "success",
  "sid": "trace-abc-001",
  "type": "variable",
  "text": "你好",
  "varText": "你好",
  "showText": "你好",
  "end": false,
  "server_vad": false,
  "vad_count": 0,
  "resultNum": 1
}
```

#### Final Result Frame (Fixed)
```json
{
  "code": 0,
  "msg": "success",
  "sid": "trace-abc-001",
  "type": "fixed",
  "text": "你好世界。",
  "showText": "你好世界。",
  "end": true,
  "server_vad": false,
  "vad_count": 0,
  "resultNum": 2
}
```

### Error Codes
Business Error Code| Description| Solution  
---|---|---  
202001| param error:xx| Check parameters  
202002| idle timeout error: xx| Connection idle timeout  
202003| server internal error: xx| Contact support and submit a ticket with the request_id  
202004| asr timeout error: xx| Recognition timeout (default upper limit 600000 ms)  
202005| decode error: xx| Audio decode failure
```

--------------------------------

### Manually Start OpenClaw Gateway (Default Port)

Source: https://maas.unisound.com/docs/toolAI/openclaw

Starts the OpenClaw gateway using the default port. This is a simpler command for manual gateway startup.

```Bash
openclaw gateway --verbose
```

--------------------------------

### Connect and Send Start Frame for One-shot ASR

Source: https://maas.unisound.com/docs/guide/speech/oneshot-asr

This Python snippet demonstrates how to establish a WebSocket connection to the One-shot ASR API, send the initial 'start' frame with audio configuration, and stream binary audio data. It requires an API key and the 'websockets' library.

```Python
"""
One-shot ASR over WebSocket.
Requires API_KEY in the environment and: pip install websockets
"""
import asyncio
import json
import os

import websockets

API_KEY = os.environ["API_KEY"]
MODEL = "u2-asr"
TRACE_ID = "trace-demo-001"
WS_URL = (
    f"wss://maas-api.hivoice.cn/v1/ws/asr/oneshot"
    f"?model={MODEL}&trace_id={TRACE_ID}"
)

START_FRAME = {
    "type": "start",
    "request_id": TRACE_ID,
    "format": "pcm",
    "sample": "16k",
    "variable": "true",
    "punctuation": "true",
    "post_proc": "true",
    "server_vad": "false",
    "context": "Customer service call",
    "hotwords": ["Unisound"],
}


async def run(pcm_path: str):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(WS_URL, additional_headers=headers) as ws:
        await ws.send(json.dumps(START_FRAME))
        with open(pcm_path, "rb") as f:
            while chunk := f.read(3200):
                await ws.send(chunk)
        await ws.send(json.dumps({"type": "end"}))
        while True:
            msg = json.loads(await ws.recv())
            print(msg)
            if msg.get("end"):
                break


if __name__ == "__main__":
    asyncio.run(run("path/to/audio.pcm"))

```

--------------------------------

### Verify Hermes Agent Installation

Source: https://maas.unisound.com/docs/toolAI/hermes-agent

Run this command to confirm that the Hermes Agent has been installed successfully. A version number indicates success.

```Bash
hermes --version
```

--------------------------------

### Verify Kilo Code CLI Installation

Source: https://maas.unisound.com/docs/toolAI/kilo-code

Verify the Kilo Code CLI installation by checking its version. A displayed version number indicates a successful installation.

```Shell
kilocode --version
```

--------------------------------

### Check Node.js Version

Source: https://maas.unisound.com/docs/toolAI/openclaw

Verify if Node.js version 22 or later is installed. This is a prerequisite for installing OpenClaw.

```Bash
node --version
```

--------------------------------

### Manually Start OpenClaw Gateway

Source: https://maas.unisound.com/docs/toolAI/openclaw

Starts the OpenClaw gateway manually on a specific port. Use this if automatic startup fails or for custom port configurations.

```Bash
openclaw gateway --port 18789 --verbose
```

--------------------------------

### Install Claude Code CLI

Source: https://maas.unisound.com/docs/toolAI/claude-code

Install the Claude Code command-line interface globally using npm. Ensure Node.js v18.0 or later is installed.

```shell
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Server Response Example

Source: https://maas.unisound.com/docs/api/transcribe/oneshot

This is an example of a successful server response during a speech recognition session. It includes the transcribed text, session ID, and status indicators.

```json
{
  "code": 0,
  "msg": "success",
  "sid": "your_session_id",
  "type": "variable",
  "text": "",
  "varText": "hello",
  "showText": "hello",
  "end": false,
  "server_vad": false,
  "vad_count": 0,
  "resultNum": 1
}
```

--------------------------------

### Oneshot API Start Frame

Source: https://maas.unisound.com/docs/api/transcribe/oneshot

Send the 'start' frame to initiate a transcription session. Specify audio format, sample rate, and other processing options.

```json
# Text frame: start
{
  "type": "start",
  "request_id": "trace-abc-001",
  "format": "opus",
  "sample": "16k",
  "variable": "true",
  "punctuation": "true",
  "post_proc": "true",
  "server_vad": "false",
  "context": "Customer service call",
  "hotwords": ["Unisound"]
}
```

--------------------------------

### Invoice Information Extraction Example

Source: https://maas.unisound.com/docs/guide/ocr/ocr-extract

Example of extracting invoice information, strictly following the provided schema for output.

```JSON
{
  "invoice_no": "25117000001021449288",
  "date": "2025-08-07",
  "items": [
    {
      "name": "*Transportation services*Passenger transport service fee",
      "unit_price": "105.95",
      "quantity": "1",
      "total": "105.95"
    }
  ]
}

```

--------------------------------

### Retrieve File Response Example

Source: https://maas.unisound.com/docs/api/file-management/retrieve

This is a successful JSON response for the Retrieve File API, showing file details and base response information.

```json
{
  "file": {
    "file_id": 871009177767936,
    "bytes": 6863158,
    "created_at": 1774268796,
    "filename": "test.mp3",
    "purpose": "ocr_async_md",
    "download_url": "http://www.test.com/test.md"
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

--------------------------------

### Retrieve File Example

Source: https://maas.unisound.com/docs/api/file-management/retrieve

Use this cURL command to retrieve file details using the file_id. Ensure you replace <api_key> with your actual API key.

```curl
curl --request GET \
  --url 'https://maas-api.hivoice.cn/v1/files/retrieve?file_id=871009177767936' \
  --header 'Authorization: Bearer <api_key>'
```

--------------------------------

### Realtime Transcription Connection and Session

Source: https://maas.unisound.com/docs/api/transcribe/realtime

This section details how to establish a WebSocket connection for real-time transcription and send control frames like 'start' and 'end'. It also shows an example of an interim result frame.

```APIDOC
## Connect (wscat example)

```bash
wscat -c "wss://maas-api.hivoice.cn/v1/audio/asr/realtime?model=u2-asr" \
  -H "Authorization: Bearer <api_key>"
```

### Text frame: start

```json
{
  "type": "start",
  "data": {
    "format": "opus",
    "sample": "16k",
    "variable": "true",
    "punctuation": "true",
    "post_proc": "true",
    "max_end_silence": "500",
    "context": "Product name is XiaoYun Assistant",
    "hotwords": ["XiaoYun","ASR"]
  }
}
```

### Binary frames: encoded audio chunks (not Base64)

### Text frame: end

```json
{ "type": "end" }
```

### ResultVO (Interim)

```json
{
  "code": 0,
  "msg": "success",
  "sid": "a1b2c3d4e5f6478990abcdef12345678",
  "type": "variable",
  "text": "你好",
  "start_time": null,
  "end_time": null,
  "end": false
}
```
```

--------------------------------

### OpenCode Configuration File

Source: https://maas.unisound.com/docs/toolAI/opencode

Example JSON configuration for OpenCode, specifying the Unisound U2 model provider with its base URL and API key. Replace UNISOUND_API_KEY and BASE_URL with your actual credentials.

```JSON
{
  "$schema": "https://opencode.ai/config.json",
	"provider": {
		"unisound": {
			"npm": "@ai-sdk/openai-compatible",
			"name": "Unisound U2",
			"options": {
				"baseURL": "BASE_URL",
				"apiKey": "UNISOUND_API_KEY"
			}
		}
	},
	"models": {
		"u2": {
			"name": "u2",
			"limit": {
				"context": 196608,
				"output": 65535
			},
			"modalities": {
				"input": [
					"text"
				],
				"output": [
					"text"
				]
		}
	}
}
}
```

--------------------------------

### Oneshot API Connection Example

Source: https://maas.unisound.com/docs/api/transcribe/oneshot

Connect to the Unisound ASR WebSocket API using wscat. Ensure you replace `<api_key>` with your actual API key and adjust the trace_id.

```bash
# Connect (wscat example)
wscat -c "wss://maas-api.hivoice.cn/v1/ws/asr/oneshot?model=u2-asr&trace_id=trace-abc-001" \
  -H "Authorization: Bearer <api_key>"
```

--------------------------------

### Verify Claude Code Installation

Source: https://maas.unisound.com/docs/toolAI/claude-code

Verify the successful installation of Claude Code by checking its version. This command should return a version number if installed correctly.

```shell
claude --version
```

--------------------------------

### Test API Call with OpenAI SDK

Source: https://maas.unisound.com/docs/token-plan/quickstart

Make a sample chat completion API call using the configured OpenAI SDK and your Token Plan API key. This verifies your setup and demonstrates basic API interaction.

```python
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="u2",
    messages=[
        {"role": "user", "content": "你好"},
    ],
)

print(response.choices[0].message.content)
```

--------------------------------

### Client Start Message

Source: https://maas.unisound.com/docs/api/transcribe/oneshot

Send this JSON message to initiate a one-shot speech recognition session. Configure audio format, sample rate, and processing options like punctuation and VAD.

```json
{
  "type": "start",
  "request_id": "your_session_id",
  "format": "pcm",
  "sample": "16k",
  "variable": "true",
  "punctuation": "true",
  "post_proc": "true",
  "server_vad": "false",
  "max_start_silence": 2000,
  "max_end_silence": 500,
  "context": "some context here",
  "hotwords": ["word1", "word2"]
}
```

--------------------------------

### Upload Prompt Audio using cURL

Source: https://maas.unisound.com/docs/api/voice-design/upload-prompt

Use this cURL command to upload a prompt audio file for voice cloning. Ensure you replace `<api_key>` with your actual API key and `example.wav` with your audio file path.

```curl
curl --request POST \
  --url https://maas-api.hivoice.cn/v1/files/upload \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'purpose=prompt_audio' \
  --form 'file=@example.wav'
```

--------------------------------

### Configure Unisound U2 via Configuration File

Source: https://maas.unisound.com/docs/toolAI/hermes-agent

Manually edit the ~/.hermes/config.yaml file to configure Hermes Agent for Unisound U2. Ensure the provider is set to 'custom' and replace BASE_URL and UNISOUND_API_KEY with your actual credentials.

```YAML
model:
  provider: custom
  base_url: BASE_URL
  api_key: UNISOUND_API_KEY
  default: u2
```

--------------------------------

### Configure Unisound U2 via Command Line

Source: https://maas.unisound.com/docs/toolAI/hermes-agent

Configure Hermes Agent to use Unisound U2 models by setting the provider, base URL, API key, and default model via command-line arguments. Replace BASE_URL and UNISOUND_API_KEY with your actual credentials.

```Bash
hermes config set model.provider custom
hermes config set model.base_url BASE_URL
hermes config set model.api_key UNISOUND_API_KEY
hermes config set model.default u2
```

--------------------------------

### Configure Environment Variables for API Access

Source: https://maas.unisound.com/docs/token-plan/quickstart

Set the OPENAI_BASE_URL and OPENAI_API_KEY environment variables to configure your application to use the Token Plan API. Replace ${YOUR_API_KEY} with your actual API key.

```bash
export OPENAI_BASE_URL=https://maas-api.hivoice.cn/v1
export OPENAI_API_KEY=${YOUR_API_KEY}
```

--------------------------------

### Messages (Anthropic-compatible)

Source: https://maas.unisound.com/docs/api/text/anthropic-compatible

Example of how to call the Messages API with a user query and the expected non-streaming JSON response.

```APIDOC
## Messages (Anthropic-compatible)

### Request

```curl
curl -X POST "https://maas-api.hivoice.cn/anthropic/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $UNISOUND_API_KEY" \
  -d '{ \
    "model": "u2", \
    "max_tokens": 1024, \
    "messages": [ \
        { \
            "role": "user", \
            "content": "你是谁？" \
        } \
    ], \
    "thinking": {"type": "disabled"} \
}'
```

### Response (200 OK)

```json
{
  "id": "msg_f2517b5e-0f5e-4443-8f92-b9b53d8a60dc",
  "type": "message",
  "role": "assistant",
  "model": "u2",
  "content": [
    {
      "type": "thinking",
      "thinking": "用户用中文问"你是谁？"，这是问我的身份。根据系统提示，我的名字是U2，由云知声（Unisound）构建。我应该用中文回答。",
      "signature": ""
    },
    {
      "type": "text",
      "text": "你好！我是U2，由云知声（Unisound）构建的AI助手。有什么我可以帮助你的吗？"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 41,
    "output_tokens": 65,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}
```
```

--------------------------------

### Reload Shell Environment

Source: https://maas.unisound.com/docs/toolAI/hermes-agent

After installation, reload your shell environment to apply the changes. Use the appropriate command for your shell.

```Bash
source ~/.bashrc  # or source ~/.zshrc
```