Xiaomi MiMo语音合成（TTS） - 数字先锋API文档

# Xiaomi MiMo API 文档（语音合成 TTS）

## 1. 接口概览

通过文本生成语音（Text-to-Speech），支持：

- 预置音色
- 风格控制（如：开心、悲伤、东北话、粤语、唱歌等）
- 细粒度语气表达（停顿、呼吸、低声、喊话等）

---

## 2. 基础信息

- **Base URL**：`https://api.cxsee.com`
- **Endpoint**：`POST /v1/chat/completions`
- **模型**：`mimo-v2-tts`（当前仅支持该模型）
- **鉴权 Header**：`api-key: sk-xxxxxxxxxxxxxxxx`
- **Content-Type**：`application/json`

---

## 3. 请求参数

### 3.1 顶层参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 固定使用 `mimo-v2-tts` |
| `messages` | array | 是 | 对话消息（**待合成文本必须放在 assistant**） |
| `audio` | object | 是 | 音频配置 |

### 3.2 `audio` 参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `format` | string | 是 | 音频格式，如 `wav` |
| `voice` | string | 是 | 预置音色 |

---

## 4. 预置音色（voice）

| 音色名 | `voice` 参数 |
|---|---|
| MiMo-默认 | `mimo_default` |
| MiMo-中文女声 | `default_zh` |
| MiMo-英文女声 | `default_en` |

> 当前不支持音色克隆。

---

## 5. 消息格式要求（非常重要）

1. **待合成目标文本必须放在 `assistant` 角色消息中**。
2. `user` 角色消息是可选参数，但建议保留（可辅助语气风格表现）。
3. 如需指定整体风格，必须把 `<style>...</style>` 放在目标文本开头。
4. 如需“唱歌”风格，建议严格使用：`<style>唱歌</style>歌词内容`（标签置于最开头）。

---

## 6. 风格控制

### 6.1 整体风格标签

格式：

```text
<style>风格1 风格2</style>待合成文本
```

支持单个或多个风格（分隔符不限制）。

常见风格示例：

- 语速：`变快` / `变慢`
- 情绪：`开心` / `悲伤` / `生气`
- 角色：`孙悟空` / `林黛玉`
- 风格：`悄悄话` / `夹子音` / `台湾腔`
- 方言：`东北话` / `四川话` / `河南话` / `粤语`
- 特殊：`唱歌`

示例：

```text
<style>开心</style>明天就是周五了，真开心！
<style>东北话</style>哎呀妈呀，这天儿也忒冷了吧！
<style>粤语</style>呢个真係好正啊！
<style>唱歌</style>原谅我这一生不羁放纵爱自由……
```

### 6.2 细粒度表达（音频标签）

你也可以在文本中加入舞台提示/语气提示，实现更细粒度效果，例如：

- （紧张，深呼吸）
- （语速加快）
- （小声）
- （沉默片刻）
- （咳嗽）
- （提高音量喊话）

示例：

```text
（紧张，深呼吸）呼……冷静，冷静。不就是一个面试吗……
（语速加快）自我介绍已经背了五十遍了，应该没问题的。
（小声）哎呀，领带歪没歪？
```

---

## 7. 调用示例

### 7.1 基础示例（WAV + 默认音色）

```bash
curl --location --request POST 'https://api.cxsee.com/v1/chat/completions' \
--header "api-key: sk-xxxxxxxxxxxxxxxx" \
--header "Content-Type: application/json" \
--data-raw '{
  "model": "mimo-v2-tts",
  "messages": [
    {
      "role": "user",
      "content": "Please read this sentence in a cheerful tone."
    },
    {
      "role": "assistant",
      "content": "<style>开心</style>明天就是周五了，真开心！"
    }
  ],
  "audio": {
    "format": "wav",
    "voice": "mimo_default"
  }
}'
```

### 7.2 中文女声 + 方言风格示例

```bash
curl --location --request POST 'https://api.cxsee.com/v1/chat/completions' \
--header "api-key: sk-xxxxxxxxxxxxxxxx" \
--header "Content-Type: application/json" \
--data-raw '{
  "model": "mimo-v2-tts",
  "messages": [
    {
      "role": "assistant",
      "content": "<style>东北话</style>哎呀妈呀，这天儿也忒冷了吧！"
    }
  ],
  "audio": {
    "format": "wav",
    "voice": "default_zh"
  }
}'
```

### 7.3 唱歌风格示例（推荐格式）

```bash
curl --location --request POST 'https://api.cxsee.com/v1/chat/completions' \
--header "api-key: sk-xxxxxxxxxxxxxxxx" \
--header "Content-Type: application/json" \
--data-raw '{
  "model": "mimo-v2-tts",
  "messages": [
    {
      "role": "assistant",
      "content": "<style>唱歌</style>原谅我这一生不羁放纵爱自由……"
    }
  ],
  "audio": {
    "format": "wav",
    "voice": "mimo_default"
  }
}'
```

---

## 8. 响应说明

接口返回遵循 Chat Completions 响应结构。
在 TTS 场景下，返回中会包含模型输出及对应音频结果（具体字段以实际网关返回为准）。

建议接入时：

1. 先打印完整 JSON 响应确认音频字段位置；
2. 按字段读取音频数据（如 base64）并保存为 `wav` 文件；
3. 客户端播放生成的音频文件。

---

## 9. 错误码

| HTTP 状态码 | 含义 |
|---|---|
| 400 | 请求参数错误（如 model/消息格式错误） |
| 401 | API Key 无效或缺失 |
| 403 | 无权限使用 TTS 模型 |
| 404 | 接口路径不存在 |
| 429 | 请求过快，触发限流 |
| 500 | 服务内部错误 |
| 503 | 服务暂不可用 |

错误示例：

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "TTS target text must be in assistant message"
  }
}
```

---

## 10. 最佳实践

- 将长文本按段切分后并行/串行合成，降低超时风险；
- 固定 `voice`，只变化 `<style>`，可获得更一致的人声体验；
- 对“唱歌”场景，务必将 `<style>唱歌</style>` 置于文本最前；
- 生产环境对 429/503 做指数退避重试；
- 不要在前端暴露 API Key。

---

上一篇：配置文件增加数字先锋API模型下一篇：文章封面生成示例