# 文本转语音接口 (/docs/user/api/model/audio)



# 文本转语音接口 [#文本转语音接口]

平台提供 AI Platform 兼容的文本转语音接口。是否可用取决于当前 API keys 的分组和模型目录：
**先在 `GET /v1/models` 中确认存在可用的音频模型**，再调用本接口。

## 请求 [#请求]

| 项目  | 值                                 |
| --- | --------------------------------- |
| 方法  | `POST`                            |
| 路径  | `/v1/audio/speech`                |
| 认证  | `Authorization: Bearer <API_KEY>` |
| 请求头 | `Content-Type: application/json`  |
| 响应  | **二进制音频**（不是 JSON）                |

<div className="lp-docs-split">
  <div className="lp-docs-steps">
    返回的是**二进制音频**，不是 JSON —— 所以用 `--output`（或 `-o`）
    把响应直接写成文件。把它当 JSON 解析会得到一个空响应体。

    `voice` 的可用取值取决于当前模型，不是所有模型都接受 `alloy`。
  </div>

  <CodeAside title="请求">
    ```bash
    curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
      -H "Authorization: Bearer $LOCOPAL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "从 /v1/models 选择的音频模型 ID",
        "input": "欢迎使用 LocoPal Ai。",
        "voice": "alloy",
        "response_format": "mp3"
      }' \
      --output speech.mp3
    ```
  </CodeAside>
</div>

## 请求参数 [#请求参数]

| 参数                | 类型     | 说明                                       |
| ----------------- | ------ | ---------------------------------------- |
| `model`           | string | 必填。`GET /v1/models` 返回的音频模型 `data[].id`。 |
| `input`           | string | 必填。要合成的文本。长度上限以实际模型为准。                   |
| `voice`           | string | 音色名称。**可用音色取决于当前模型**，请以模型详情为准。           |
| `response_format` | string | 输出音频格式，例如 `mp3`。支持的格式以实际模型为准。            |
| `speed`           | number | 语速。是否支持及取值范围以实际模型为准。                     |

> 音色、格式与语速的可用范围**因模型而异**。不要假设所有模型都支持 `alloy` 或 `mp3`，
> 也不要把某个模型的音色列表写死在代码里。

## 响应 [#响应]

### 成功 [#成功]

成功响应的**正文是二进制音频数据，不是 JSON**。直接写入文件或流式转发给客户端即可。

```bash
# 保存为文件
curl ... --output speech.mp3

# 检查确实是音频而不是 JSON
file speech.mp3
```

### 失败 [#失败]

失败时返回带 `error` 对象的非 `2xx` 响应，结构与模型接口一致：

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}
```

常见的失败原因：

| 情况        | 表现                       | 处理                          |
| --------- | ------------------------ | --------------------------- |
| 分组里没有音频模型 | `model_not_found` 或模型不可用 | 用 `GET /v1/models` 确认可用音频模型 |
| 音色不被该模型支持 | `invalid_parameter`      | 改用该模型支持的音色                  |
| 格式不被该模型支持 | `invalid_parameter`      | 改用支持的 `response_format`     |
| 请求过于频繁    | HTTP `429`               | 按提示退避重试                     |

## 服务端接入建议 [#服务端接入建议]

文本转语音是**同步**接口，响应即音频数据，接入时注意：

1. **不要把它当 JSON 解析**。先判断 HTTP 状态和 `Content-Type`，
   只有失败时才按 JSON 读取 `error`；
2. **不要把音频直接透传给浏览器时忘记设置 `Content-Type`**，
   否则浏览器会把它当文本处理；
3. **控制 `input` 长度**。超长文本建议在业务侧切分，分段合成后再拼接，
   避免单次请求超限；
4. **音频文件建议转存**到自己的存储，不要长期依赖平台返回的临时结果；
5. 业务后端应缓存高频重复的合成结果，避免重复计费。

## 异步音频任务 [#异步音频任务]

除本同步接口外，平台还提供异步的音频生成能力（如配乐、音效）。
这类任务的状态与制品在控制台「任务日志」中查询，处理方式与
[视频任务](/docs/user/api/model/video/create)类似：
创建后保存任务 ID，用查询接口轮询到终态，**不要重复创建**。

## 计费 [#计费]

音频接口的计费方式以模型广场的模型详情为准，可能按 Token、按次或按时长计费。
计费与结算规则见[计费与账单](/docs/user/help/billing)。

## 相关文档 [#相关文档]

* [接口总览](/docs/user/api/overview)
* [认证与基础规范](/docs/user/api/authentication)
* [错误码与排查](/docs/user/api/errors)
* [快速开始：第一次文本转语音调用](/docs/user/start/quick-start)