> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetoken.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax Speech API

> MiniMax 语音合成（Speech 2.8 / 2.6 / 02，HD 与 Turbo）通过 VibeToken 提供：发送文本和音色，同一个响应里直接拿回音频。

## 概览

VibeToken 上的 MiniMax 语音合成（TTS）模型，经 MiniMax 官方 API 提供，
对外是兼容 OpenAI 的 `POST /v1/audio/speech`。调用是**同步**的：响应体就是
音频文件本身，没有需要轮询的生成 id。

| | |
| - | - |
| **提供方** | MiniMax（官方 API） |
| **模态** | 音频 |
| **任务** | `text-to-speech` |
| **输入** | 文本（计费字符数少于 10,000） |
| **输出** | 音频字节：`mp3`、`wav`、`flac`、`pcm` 或 `opus` |

## 模型

| 模型 ID | 档位 | 说明 |
| - | - | - |
| `minimax/speech-2.8-hd` | HD | 最新一代，保真度最高。 |
| `minimax/speech-2.8-turbo` | Turbo | 最新一代，更快、成本更低。 |
| `minimax/speech-2.6-hd` | HD | 保真度最高。 |
| `minimax/speech-2.6-turbo` | Turbo | 更快、成本更低。 |
| `minimax/speech-02-hd` | HD | 保真度最高。 |
| `minimax/speech-02-turbo` | Turbo | 更快、成本更低。 |

**HD** 是保真度最高的一档，适合旁白、有声书等需要细听的场景。**Turbo**
速度更快、成本更低，适合交互式或大批量调用。

## 端点

```http theme={null}
POST https://vibetoken.cn/v1/audio/speech
```

| 请求头 | 值 |
| - | - |
| `Authorization` | `Bearer sk-rb-xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |

请使用**个人** API Key。与其他媒体端点一样，该端点不接受组织 Key。

## 快速开始

```bash cURL theme={null}
curl https://vibetoken.cn/v1/audio/speech \
  -H "Authorization: Bearer $VIBETOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/speech-2.8-turbo",
    "voice": "Chinese (Mandarin)_News_Anchor",
    "input": "欢迎使用 VibeToken，一个密钥，调用所有模型。"
  }' \
  --output speech.mp3
```

```python Python (OpenAI SDK) theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-rb-xxxxxxxxxxxx",
    base_url="https://vibetoken.cn/v1",
)

response = client.audio.speech.create(
    model="minimax/speech-2.8-turbo",
    voice="Chinese (Mandarin)_News_Anchor",
    input="欢迎使用 VibeToken，一个密钥，调用所有模型。",
)
response.write_to_file("speech.mp3")
```

```javascript Node.js (OpenAI SDK) theme={null}
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.VIBETOKEN_API_KEY,
  baseURL: "https://vibetoken.cn/v1",
});

const response = await client.audio.speech.create({
  model: "minimax/speech-2.8-turbo",
  voice: "Chinese (Mandarin)_News_Anchor",
  input: "欢迎使用 VibeToken，一个密钥，调用所有模型。",
});
fs.writeFileSync("speech.mp3", Buffer.from(await response.arrayBuffer()));
```

SDK 会原样发送 `voice`，因此直接传 MiniMax 音色 id 即可。

## 请求体

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 上表中的任一模型 id。 |
| `input` | string | 是 | 要朗读的文本。计费字符数必须少于 10,000（见[计费](#计费)），可包含[停顿标记](#停顿)。 |
| `voice` | string | 是 | MiniMax 系统音色 id，见[音色](#音色)。 |
| `response_format` | string | 否 | `mp3`（默认）、`wav`、`flac`、`pcm` 或 `opus`；不提供 `aac`。 |
| `speed` | number | 否 | 语速，`0.5` 到 `2`，默认 `1`。 |
| `stream_format` | string | 否 | 仅支持 `audio`；`sse` 返回 `400`。 |
| `instructions` | string | 否 | 为兼容 OpenAI 而接受，但会被忽略。 |
| `provider.options.minimax` | object | 否 | MiniMax 专有参数，见 [MiniMax 选项](#minimax-选项)。 |

其他任何字段都会返回 `400`。

## 响应

成功时返回 `200`，响应体就是原始音频字节：

| 响应头 | 值 |
| - | - |
| `Content-Type` | `audio/mpeg`（mp3）、`audio/wav`、`audio/flac`、`audio/pcm` 或 `audio/ogg`（opus） |
| `X-Generation-Id` | 生成 id，可在你的[日志](https://vibetoken.cn/logs)与用量中定位这次调用。 |

把响应体直接写入文件即可（curl 用 `--output speech.mp3`）。

带上 `Idempotency-Key` 请求头即可安全重试：重复同一个 key 会返回同一段音频，
不会重复计费（若首次请求仍在进行或已失败，则返回 `409`）。

## 音色

`voice` 接受任意 MiniMax 系统音色 id。可以先从这些开始：

| 音色 id | 语言 |
| - | - |
| `English_expressive_narrator` | 英语 |
| `English_radiant_girl` | 英语 |
| `English_magnetic_voiced_man` | 英语 |
| `English_CalmWoman` | 英语 |
| `Chinese (Mandarin)_News_Anchor` | 普通话 |
| `Chinese (Mandarin)_Radio_Host` | 普通话 |
| `male-qn-qingse` | 普通话 |
| `Cantonese_GentleLady` | 粤语 |
| `Japanese_IntellectualSenior` | 日语 |
| `Korean_AthleticGirl` | 韩语 |
| `Spanish_Narrator` | 西班牙语 |
| `Portuguese_SentimentalLady` | 葡萄牙语 |

音色 id 区分大小写，部分包含空格和括号，请按原样传入。完整列表见 MiniMax 的
[系统音色 id](https://platform.minimax.io/docs/faq/system-voice-id)。
未知的音色 id 会返回 `400`，并附带 MiniMax 的原始提示。

## MiniMax 选项

MiniMax 自有的控制参数放在 `provider.options.minimax` 下。所有键均为可选；
未知的键会返回 `400`。

| 键 | 类型 | 说明 |
| - | - | - |
| `vol` | number | 音量，大于 `0`、最大 `10`，默认 `1`。 |
| `pitch` | integer | 音调，以半音为单位，`-12` 到 `12`，默认 `0`。 |
| `emotion` | string | `happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、`calm`、`fluent` 或 `whisper`。不传则由模型自行判断。 |
| `text_normalization` | boolean | 将数字、日期等按口语形式朗读。 |
| `latex_read` | boolean | 朗读 LaTeX 公式。 |
| `sample_rate` | integer | `8000`、`16000`、`22050`、`24000`、`32000` 或 `44100`。 |
| `bitrate` | integer | `32000`、`64000`、`128000` 或 `256000`，仅 `mp3`。 |
| `channel` | integer | `1`（单声道）或 `2`（立体声）。 |
| `language_boost` | string | 强化对指定语言的识别，例如 `auto`、`English`、`Chinese`。 |
| `pronunciation_dict` | object | 自定义读音，原样传给 MiniMax。 |
| `voice_modify` | object | 音效调节（音高、强度、音色），原样传给 MiniMax。 |
| `text_normalization_mode` | string | 文本规范化模式，原样传给 MiniMax。 |

```bash theme={null}
curl https://vibetoken.cn/v1/audio/speech \
  -H "Authorization: Bearer $VIBETOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/speech-2.8-hd",
    "voice": "Chinese (Mandarin)_News_Anchor",
    "input": "今天的新闻到此结束，感谢收听。",
    "response_format": "wav",
    "speed": 1.1,
    "provider": {
      "options": {
        "minimax": {
          "emotion": "calm",
          "sample_rate": 32000,
          "channel": 1,
          "language_boost": "Chinese"
        }
      }
    }
  }' \
  --output news.wav
```

使用 OpenAI Python SDK 时，通过 `extra_body` 传入同样的对象：

```python theme={null}
response = client.audio.speech.create(
    model="minimax/speech-2.8-hd",
    voice="English_expressive_narrator",
    input="Chapter one.",
    extra_body={"provider": {"options": {"minimax": {"emotion": "calm", "vol": 1.2}}}},
)
```

## 停顿

在 `input` 中任意位置插入 `<#x#>` 即可停顿，`x` 为秒数，范围 `0.01` 到
`99.99`：

```json theme={null}
{ "input": "预备。<#0.5#>开始！" }
```

## 计费

语音合成**按输入字符**计费。一个中日韩汉字计 2 个字符；其他字符（字母、数字、
假名、标点、空格）计 1 个。10,000 字符的上限也按同一口径计算，因此单次请求最多
约 9,999 个拉丁字符，或约 5,000 个汉字。

请求到达时，VibeToken 会按输入的计费字符数从余额中预扣（hold）相应费用。音频
返回后，按 MiniMax 实际计费的字符数结算。调用失败会释放预扣，不产生费用。

各模型的费率见[定价页](https://vibetoken.cn/pricing)，也可以通过
[Models API](https://docs.vibetoken.cn/zh/api-reference/models.md) 查询：

```http theme={null}
GET /api/models/minimax%2Fspeech-2.8-turbo/pricing
```

## 错误

错误使用标准的 `/v1` JSON 错误结构（见[错误码](https://docs.vibetoken.cn/zh/essentials/errors.md)），不会返回
音频字节。

| 状态码 | 场景 |
| - | - |
| `400` | 缺少或为空的 `input` / `voice`、`input` 超出字符上限、不支持的 `response_format`、`speed` 越界、未知字段或未知的 MiniMax 选项。 |
| `400` | MiniMax 拒绝了某个参数，例如音色 id 不存在。提示信息为 MiniMax 原文。 |
| `400` | 输入文本被内容安全策略拦截。 |
| `402` | 余额不足以完成预扣。 |
| `429` | 上游限流，请稍后重试。 |
| `503` | 语音服务不可达或超时。 |

```json theme={null}
{ "error": { "type": "invalid_request_error", "message": "`voice` is required: a MiniMax voice id such as `English_Graceful_Lady` or `male-qn-qingse`", "code": 400 } }
```

## 另请参阅

* [音频 API 参考](https://docs.vibetoken.cn/zh/api-reference/audio.md)
* [模型总览](https://docs.vibetoken.cn/zh/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.