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

# 文字转语音

> 将文本转换为语音音频（返回 MP3 二进制数据）。

将文本转换为语音。返回的是原始音频字节（`audio/mpeg`），而不是 JSON。

<Note>
  响应内容是一个二进制 MP3 文件，而不是 JSON 对象。`Content-Type` 响应头为 `audio/mpeg`。
</Note>

## 身份验证

需要提供 Bearer 令牌。详见[身份验证](/api-reference/authentication)。

## 请求体

<ParamField body="text" type="string" required>
  要转换为语音的文本。最多 4,096 个字符。
</ParamField>

<ParamField body="voice" type="string" default="theo-voice-classic">
  可选的 Theo 语音标识符。省略则使用默认语音。未知的取值会回退到 `theo-voice-classic`。

  | 语音 | 特点 |
  | - | - |
  | `theo-voice-classic` | 中性、多用途——默认音色 |
  | `theo-voice-bright` | 明亮、清晰、活泼 |
  | `theo-voice-storyteller` | 叙事感强、富有表现力 |
  | `theo-voice-deep` | 低沉、权威 |
  | `theo-voice-warm` | 温暖、专业 |
  | `theo-voice-soft` | 柔和、沉稳 |
</ParamField>

<ParamField body="speed" type="number" default="1.0">
  播放速度倍率（0.25–4.0）。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/audio/tts \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Welcome to Theo. How can I help you today?",
      "voice": "theo-voice-warm",
      "speed": 1.0
    }' \
    --output speech.mp3
  ```

  ```typescript SDK theme={null}
  const audioBuffer = await theo.tts({
    text: "Welcome to Theo. How can I help you today?",
    voice: "theo-voice-warm",
    speed: 1.0,
  });

  // audioBuffer is an ArrayBuffer — write to file or stream to client
  import { writeFileSync } from "fs";
  writeFileSync("output.mp3", Buffer.from(audioBuffer));
  ```
</CodeGroup>

## 响应

响应体是原始 MP3 音频字节。

| 响应头 | 值 |
| - | - |
| `Content-Type` | `audio/mpeg` |
| `Content-Length` | 文件大小（字节数） |
| `X-Request-Id` | 唯一请求 ID（前缀为 `tts_`） |

## 错误

| 状态码 | 错误码 | 说明 |
| - | - | - |
| 400 | `missing_text` | 缺少必填的 `text` 参数 |
| 401 | `invalid_api_key` | API 密钥缺失或无效 |
| 502 | `tts_provider_error` | Theo 语音引擎返回错误——请重试 |
| 503 | `tts_unavailable` | 此实例未配置文字转语音功能 |


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