> ## 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.

# 音频（语音合成）

> POST /v1/audio/speech：兼容 OpenAI 的语音合成，响应中直接返回音频字节。

## 端点

```
POST https://vibetoken.cn/v1/audio/speech
```

OpenAI / OpenRouter 形态的语音合成。对 MiniMax 语音模型，调用是**同步**的：
响应体就是音频文件，没有需要轮询的生成 id。OpenAI SDK 的 `audio.speech.create`
可直接使用。

模型：`minimax/speech-2.8-hd`、`minimax/speech-2.8-turbo`、
`minimax/speech-2.6-hd`、`minimax/speech-2.6-turbo`、`minimax/speech-02-hd`、
`minimax/speech-02-turbo`。音色、选项与示例见
[MiniMax Speech 快速开始](https://docs.vibetoken.cn/zh/minimax-speech-api/quickstart.md)。

## 请求头

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

仅支持个人 API Key；与其他媒体端点一样，不接受组织 Key。

## 请求体

**model** `string` *required*

语音模型 id，例如 `minimax/speech-2.8-turbo`。

**input** `string` *required*

要合成的文本。计费字符数必须少于 10,000：一个中日韩汉字计 2，其他字符计 1。
文本中任意位置可以插入停顿标记，例如 `<#0.5#>`（秒，`0.01` 到 `99.99`）。

**voice** `string` *required*

MiniMax 系统音色 id，例如 `English_expressive_narrator`、
`Chinese (Mandarin)_News_Anchor`、`Spanish_Narrator`、`male-qn-qingse`。
完整列表：[MiniMax 系统音色 id](https://platform.minimax.io/docs/faq/system-voice-id)。

**response\_format** `string` (default: mp3)

`mp3`、`wav`、`flac`、`pcm` 或 `opus`（Ogg/Opus）。这些模型不提供 OpenAI 的
`aac`，传入会返回 `400`。

**speed** `number` (default: 1)

语速，`0.5` 到 `2`（比 OpenAI 的 `0.25` 到 `4` 窄，超出范围返回 `400`）。

**instructions** `string`

为兼容 OpenAI 而接受，但会被忽略。

**stream\_format** `string` (default: audio)

仅支持 `audio`（响应中返回完整文件），`sse` 返回 `400`。

**provider.options.minimax** `object`

可选的 MiniMax 控制参数：`vol`（大于 0，最大 10）、`pitch`（-12 到 12）、
`emotion`（`happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、
`calm`、`fluent`、`whisper`）、`text_normalization`、`latex_read`、
`sample_rate`（8000 / 16000 / 22050 / 24000 / 32000 / 44100）、`bitrate`
（32000 / 64000 / 128000 / 256000，仅 mp3）、`channel`（1 或 2）、
`language_boost`（例如 `auto`、`English`、`Chinese`）、`pronunciation_dict`、
`voice_modify`、`text_normalization_mode`。详见
[MiniMax 选项](https://docs.vibetoken.cn/zh/minimax-speech-api/quickstart.md#minimax-选项)。

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

## 示例

```bash cURL theme={null}
curl https://vibetoken.cn/v1/audio/speech \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/speech-2.8-turbo",
    "voice": "Chinese (Mandarin)_News_Anchor",
    "input": "你好，世界！"
  }' \
  --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="你好，世界！",
)
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: "sk-rb-xxxxxxxxxxxx", baseURL: "https://vibetoken.cn/v1" });

const response = await client.audio.speech.create({
  model: "minimax/speech-2.8-turbo",
  voice: "Chinese (Mandarin)_News_Anchor",
  input: "你好，世界！",
});
fs.writeFileSync("speech.mp3", Buffer.from(await response.arrayBuffer()));
```

## 响应

返回 `200`，响应体为原始音频字节。

| 响应头 | 值 |
| - | - |
| `Content-Type` | `audio/mpeg`、`audio/wav`、`audio/flac`、`audio/pcm` 或 `audio/ogg`，与 `response_format` 对应 |
| `X-Generation-Id` | 本次调用的生成 id，与日志和用量中显示的一致 |

音频也会随生成记录保存，因此带同一 `Idempotency-Key`（或 `client_request_id`）
的重试会返回同一段音频，不会重复计费。若首次请求仍在进行或已失败，重试会收到
`409` 并附上该生成 id；换一个新 key 才会重新合成。`POST /v1/audio/generations`
接受相同的请求体，返回 JSON 形式的完成结果（`status: "success"`、`data[0].url`），
而不是原始音频。

## 计费

按输入字符计费（一个中日韩汉字计 2）。请求到达时按输入字符数预扣费用，音频生成后
按实际计费的字符数结算；调用失败会释放预扣。费率见[定价页](https://vibetoken.cn/pricing)。

## 错误

错误以常规的 JSON 错误结构返回（见[错误码](https://docs.vibetoken.cn/zh/essentials/errors.md)），不会返回音频。

| 状态码 | 场景 |
| - | - |
| `400` | 请求无效：缺少 `voice`、`input` 过长、不支持的格式或字段、`speed` 越界。 |
| `400` | MiniMax 拒绝了某个参数，例如音色 id 不存在；提示信息为 MiniMax 原文。 |
| `400` | 输入文本被内容安全策略拦截。 |
| `402` | 余额不足。 |
| `429` | 被限流，请稍后重试。 |
| `503` | 语音服务不可达或超时。 |

## 其他音频模型

其他提供方的音频模型在同一端点（以及 `POST /v1/audio/generations`）上走异步任务
流程：POST 返回 `{id, status: "pending"}`，然后轮询 `GET /v1/audio/generations/{id}`，
直到 `data[].url` 出现。目前没有上架这类模型；轮询方式见
[异步任务](https://docs.vibetoken.cn/zh/essentials/async-tasks.md)。


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