> ## 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.