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

# OpenAI 語音合成 API（/v1/audio/speech）

> OpenAI generation 整合指南 - Ace Data Cloud

將文本合成為自然語音，**完全兼容 OpenAI 的 `/v1/audio/speech`**。任何 OpenAI SDK 只需把 `base_url` 指向 `https://api.acedata.cloud`、把密鑰換成你的 AceData Token 即可直接使用。接口同步返回音頻字節流。

* **請求地址**：`POST https://api.acedata.cloud/v1/audio/speech`（別名 `POST /openai/audio/speech`）
* **鑑權**：請求頭 `Authorization: Bearer {token}`
* **計費**：按請求文本字節數計費，約為 OpenAI 官方價的 85%（見下表）。

## 請求參數

| 字段 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `input` | string | 是 | 要合成的文本。 |
| `model` | string | 否 | `tts-1`（更快）或 `tts-1-hd`（更高音質，默認）。 |
| `voice` | string | 否 | `alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer` 之一，默認 `alloy`。 |
| `response_format` | string | 否 | `mp3`(默認)、`opus`、`aac`、`flac`、`wav`、`pcm`。 |
| `speed` | number | 否 | 語速 0.25–4.0，默認 1.0。 |

## 示例

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/speech' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -o speech.mp3 \
  -d '{
    "model": "tts-1-hd",
    "input": "What if one API gave you every AI video model?",
    "voice": "nova",
    "response_format": "mp3"
  }'
```

返回的是音頻文件本身（`Content-Type: audio/mpeg`），直接寫入 `speech.mp3` 即可播放。

用官方 OpenAI Python SDK：

```python theme={null}
from openai import OpenAI
client = OpenAI(base_url="https://api.acedata.cloud/v1", api_key="{token}")
client.audio.speech.create(model="tts-1-hd", voice="nova", input="Hello from AceData.").stream_to_file("speech.mp3")
```

## 價格

| 模型 | OpenAI 官方價 | 本平台價（約 85 折） |
| - | - | - |
| `tts-1` | \$15 / 100 萬字符 | 約 \$12.75 / 100 萬字符 |
| `tts-1-hd` | \$30 / 100 萬字符 | 約 \$25.5 / 100 萬字符 |

> 按請求文本字節數計費;`official_price` 字段展示 OpenAI 官方價以便對比。

## 錯誤碼

| 狀態碼 | code | 說明 |
| - | - | - |
| 400 | `bad_request` | `input` 为空或參數非法。 |
| 401 | `authentication_failed` | token 無效。 |
| 403 | `used_up` | 餘額不足。 |
| 429 | `too_many_requests` | 請求過於頻繁。 |
| 500 | `api_error` | 上游/內部錯誤。 |


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