# 生成音频API文档

本文件介绍本平台语音生成接口、声音与格式参数、音频文件保存和错误处理，可交给 AI 编程助手完成接入。

## 接入前准备

- API 接入地址：`https://geekapi.net`，本文中的接口地址已按下载站点填写。
- 将 `sk-你的令牌` 替换为“接入密钥”页面显示的完整密钥。
- 从当前模型目录复制音频模型的 `name`。下面示例使用 `seed-audio-1.0`。
- 声音 ID、输出格式和语速范围须符合所选模型及线路规则。

可查询模型目录中的 `modelRules.audio`，查看声音列表、支持格式及语速：

```bash
curl 'https://geekapi.net/api/platform/model-catalog?scope=enabled' \
  -H 'Authorization: Bearer sk-你的令牌'
```

请让 AI 编程助手复用项目现有请求和配置方式，将密钥保存在接入方配置中，不要写入源码、日志或公开网页。

## 创建语音

```http
POST /v1/audio/speech
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

```bash
curl --fail-with-body https://geekapi.net/v1/audio/speech \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -o speech.mp3 \
  -d '{
    "model": "seed-audio-1.0",
    "input": "欢迎使用本平台统一 API。",
    "voice": "zh_female_vv_uranus_bigtts",
    "response_format": "mp3",
    "speed": 1
  }'
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，平台公开音频模型值。 |
| `input` | string | 需要转换为语音的文本。 |
| `voice` | string | 声音 ID，使用当前模型目录中的有效值。 |
| `response_format` | string | 音频格式；示例模型支持 `mp3`、`wav`、`pcm`、`opus`。 |
| `speed` | number | 语速；示例模型范围为 `0.5`–`2`，默认 `1`。 |

更换模型时须重新核对声音和参数，不能直接复用另一个模型的声音 ID。

## 响应与音频下载

该接口通常同步返回音频二进制内容。先检查 HTTP 状态和 `Content-Type`，成功后把响应体保存为与输出格式对应的文件；不要把二进制响应当 JSON 解析，也不要把错误 JSON 保存成可播放音频。

JavaScript 服务端示例：

```javascript
import { writeFile } from "node:fs/promises";

const response = await fetch("https://geekapi.net/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PLATFORM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seed-audio-1.0",
    input: "欢迎使用本平台统一 API。",
    voice: "zh_female_vv_uranus_bigtts",
    response_format: "mp3",
    speed: 1,
  }),
});

if (!response.ok) {
  throw new Error(`音频生成失败（${response.status}）：${await response.text()}`);
}
if ((response.headers.get("content-type") || "").includes("application/json")) {
  throw new Error(`接口未返回音频：${await response.text()}`);
}
await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));
```

纯网页应用可由自己的服务端保管令牌并转发响应，再由浏览器保存为 Blob 文件。直接返回音频的请求不需要视频任务轮询或回调字段。

## 错误处理

- `400`：核对文本、声音 ID、输出格式和语速范围。
- `401`：核对完整接入密钥及其是否有效。
- `402`：检查账户余额。
- `429`：降低调用频率，稍后重试。
- 网络中断或 `5xx`：保留错误信息并提示用户；避免循环自动提交相同生成请求。

接入完成后，至少验证一次成功保存、一次无效声音、一次无效密钥，以及播放器能否播放实际保存的文件。