# Audio Speech API — 语音合成（文字转语音）

Source: https://ofox.ai/zh/docs/api/openai/audio-speech

将文字转为语音。兼容 OpenAI 的 `POST /v1/audio/speech`，响应体直接是音频文件（二进制），不是 JSON。

| 系列 | 模型 | 说明 |
|---|---|---|
| ElevenLabs | `elevenlabs/eleven_v4` | 见 [ElevenLabs](https://ofox.ai/zh/docs/develop/models/elevenlabs) |
| Gemini TTS | `google/gemini-3.8-flash-tts` 等 | 见 [Gemini TTS](https://ofox.ai/zh/docs/develop/models/gemini-tts) |

`voice`、`response_format` 等参数的可选值因模型而异，请以系列页为准。

## 快速开始

- base_url: `https://api.ofox.ai/v1`
- 接口地址: `https://api.ofox.ai/v1/audio/speech`
- 模型 ID: `google/gemini-3.8-flash-tts`

**Python**

```python filename="speech.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])

with client.audio.speech.with_streaming_response.create(
    model="google/gemini-3.8-flash-tts",
    voice="Kore",
    input="你好，欢迎使用 OfoxAI 语音合成。",
    response_format="wav",
) as resp:
    resp.stream_to_file("speech.wav")
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/audio/speech \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.8-flash-tts",
    "voice": "Kore",
    "input": "你好，欢迎使用 OfoxAI 语音合成。",
    "response_format": "wav"
  }' \
  --output speech.wav
```

## 请求参数

**model** `string` · required

模型 ID，见上表。

**input** `string` · required

要合成的文字。为空时返回 400。

**voice** `string`

音色。Gemini TTS 必填，取值为 Google 的音色名（如 `Kore`）；ElevenLabs 取值为音色 ID（如 `21m00Tcm4TlvDq8ikWAM`）。OpenAI 的音色名（如 `alloy`）不适用于这两个系列。

**response_format** `string`

音频格式。可选值因模型而异：Gemini TTS 支持 `wav`、`pcm`；ElevenLabs 支持 `mp3`、`opus`、`wav`、`pcm`。传入不支持的格式返回 400。

**instructions** `string`

语气与风格说明，如「用欢快的语气朗读」。适用于 Gemini TTS。

**language_code** `string`

语言代码，如 `cmn-CN`（Gemini TTS）、`zh`（ElevenLabs）。不传时由模型根据文字判断。

**stream_format** `string` · values `sse`

传 `sse` 时以 Server-Sent Events 流式返回音频分片，适用于 Gemini TTS。

**provider_options** `object`

供应商专有参数，透传给对应供应商，例如 ElevenLabs 的 `{"elevenlabs": {"voice_settings": {...}}}`。见各系列页。

## 响应
成功时 HTTP 200，响应体为音频文件，`Content-Type` 与格式对应：

| response_format | Content-Type |
|---|---|
| `mp3` | `audio/mpeg` |
| `wav` | `audio/wav` |
| `opus` | `audio/ogg` |
| `pcm` | `audio/L16;rate=<采样率>;channels=1`，无文件头的 16 位 PCM |

请将响应体直接写入文件。出错时响应为 JSON，`Content-Type` 为 `application/json`，请先检查状态码，避免把错误信息写成音频文件。

## 常见报错
| HTTP | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 | `model and input are required.` | 缺少 `model`，或 `input` 为空 | 补全参数 |
| 400 | `voice is required for speech completion` | Gemini TTS 未传 `voice` | 传入音色名，如 `Kore` |
| 400 | `unsupported Gemini response_format: mp3` | 该模型不支持所选格式 | 改用系列页列出的格式 |
| 400 | `Request contains an invalid argument.` | Gemini TTS 的音色名不存在 | 改用有效的音色名 |
| 404 | `A voice with voice_id 'alloy' was not found.` | ElevenLabs 的音色 ID 不存在 | 改用有效的音色 ID |
| 400 `endpoint_not_supported` | `Model 'openai/gpt-5.4' does not support the /v1/audio/speech endpoint on this platform.` | 所选模型不是语音合成模型 | 改用上表中的模型 |

完整的错误码说明见[错误处理](https://ofox.ai/zh/docs/develop/guides/error-handling)。