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

# 建立語音

> 根據輸入文字產生音訊

## 請求本文

**同步請求逾時：** 這個非聊天端點會等待路由到的模型完成處理。大型輸入、長音訊或大量批次可能超過常見的 30s 用戶端預設逾時，因此請將 HTTP 用戶端逾時設定為至少 `120s`。

不同模型家族支援的可選欄位不同。TokenLab 會在路由前驗證欄位矩陣：OpenAI TTS 接受 `voice`、`instructions`、`response_format`、`stream_format`、`speed`；MiniMax 語音接受 `voice`、`voice_id`、`response_format`、`stream_format`、`speed`；Gemini TTS 接受 `prompt`、`language_code`、`voice`、`response_format`、`stream_format`、`speed`、`temperature`；更窄的 Vidu/Kling 類 TTS 路由可能只接受 `input` 和 `stream_format`。未知頂層欄位（包括 `user`）會返回 `400 unsupported_parameter`，不會被靜默忽略。

<ParamField body="model" type="string" default="tts-1">
  TTS 模型。範例包括 `tts-1`、`gpt-4o-mini-tts`、`speech-02-hd` 和 `gemini-2.5-flash-tts`。請透過 `GET /v1/models?recommended_for=tts` 取得目前推薦清單。
</ParamField>

<ParamField body="input" type="string" required>
  要用來產生音訊的文字。最多 4096 個字元。
</ParamField>

<ParamField body="voice" type="string | object">
  語音選擇器。可傳入 `nova` 等內建語音、`Kore` 等 Gemini 語音，或為相容的自訂語音傳入 `{ "id": "voice-id" }`。
</ParamField>

<ParamField body="voice_id" type="string">
  MiniMax 相容語音模型的上游原生語音選擇器。
</ParamField>

<ParamField body="instructions" type="string">
  支援此欄位的 OpenAI 相容 TTS 模型可使用的風格或朗讀指令。
</ParamField>

<ParamField body="prompt" type="string">
  Gemini TTS 的可選朗讀風格 prompt。
</ParamField>

<ParamField body="language_code" type="string">
  可選語言代碼，例如 `en-US`，適用於 Gemini、xAI 和相容 TTS 路由。
</ParamField>

<ParamField body="response_format" type="string">
  音訊格式。常見值包括 `mp3`、`opus`、`aac`、`flac`、`wav`、`pcm`；具體支援值依模型家族而定。
</ParamField>

<ParamField body="stream_format" type="string" default="audio">
  TokenLab 交付格式：`audio` 或 `sse`。`tts-1` 和 `tts-1-hd` 不支援 `stream_format=sse`。
</ParamField>

<ParamField body="speed" type="number">
  支援此欄位的模型家族可設定語速（0.25 到 4.0）。
</ParamField>

<ParamField body="temperature" type="number">
  Gemini 相容 TTS 路由的採樣溫度（0 到 2）。
</ParamField>

## 回應

以請求的格式回傳音訊檔案。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "tts-1-hd",
      "voice": "nova",
      "input": "Hello, welcome to TokenLab!"
    }' \
    --output speech.mp3
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

  response = client.audio.speech.create(
      model="tts-1-hd",
      voice="nova",
      input="Hello, welcome to TokenLab!"
  )

  response.stream_to_file("speech.mp3")
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';
  import fs from 'fs';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.audio.speech.create({
    model: 'tts-1-hd',
    voice: 'nova',
    input: 'Hello, welcome to TokenLab!'
  });

  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync('speech.mp3', buffer);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/audio/speech');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'tts-1-hd',
          'voice' => 'nova',
          'input' => 'Hello, welcome to TokenLab!'
      ])
  ]);

  $audio = curl_exec($ch);
  curl_close($ch);

  file_put_contents('speech.mp3', $audio);
  ```
</RequestExample>

## 語音範例

| 語音        | 描述         |
| --------- | ---------- |
| `alloy`   | 中性、均衡      |
| `ash`     | 平靜、沉穩      |
| `ballad`  | 富有旋律感、表現力強 |
| `coral`   | 溫暖、親切      |
| `echo`    | 溫暖、適合對話    |
| `fable`   | 表現力強、敘事感佳  |
| `nova`    | 友善、清晰      |
| `onyx`    | 低沉、具權威感    |
| `sage`    | 睿智、深思熟慮    |
| `shimmer` | 柔和、溫柔      |
| `verse`   | 動態感強、用途多元  |

## 回應範例

<ResponseExample>
  ```binary 200 OK theme={null}
  <binary audio data>
  ```
</ResponseExample>

## 重要欄位

<ResponseField name="Content-Type" type="string">API 返回的事件或訊息類型。</ResponseField>
<ResponseField name="body" type="binary">原始回應體。應直接保存，不要按 JSON 解析。</ResponseField>