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

# Tạo Giọng nói

> Tạo audio từ văn bản đầu vào

## Nội dung yêu cầu

**Timeout cho yêu cầu đồng bộ:** endpoint không phải chat này chờ model được định tuyến hoàn tất. Input lớn, audio dài, hoặc batch lớn có thể vượt quá mặc định 30s phổ biến của client, vì vậy hãy đặt timeout của HTTP client ít nhất là `120s`.

Các field tuỳ chọn được hỗ trợ khác nhau theo từng họ model. TokenLab kiểm tra ma trận field này trước khi routing: OpenAI TTS nhận `voice`, `instructions`, `response_format`, `stream_format`, và `speed`; MiniMax speech nhận `voice`, `voice_id`, `response_format`, `stream_format`, và `speed`; Gemini TTS nhận `prompt`, `language_code`, `voice`, `response_format`, `stream_format`, `speed`, và `temperature`; các route TTS hẹp hơn kiểu Vidu/Kling có thể chỉ nhận `input` và `stream_format`. Field top-level không xác định, bao gồm `user`, sẽ trả về `400 unsupported_parameter` thay vì bị bỏ qua.

<ParamField body="model" type="string" default="tts-1">
  Model TTS. Ví dụ gồm `tts-1`, `gpt-4o-mini-tts`, `speech-02-hd`, và `gemini-2.5-flash-tts`. Gọi `GET /v1/models?recommended_for=tts` để lấy danh sách hiện tại.
</ParamField>

<ParamField body="input" type="string" required>
  Văn bản dùng để tạo audio. Tối đa 4096 ký tự.
</ParamField>

<ParamField body="voice" type="string | object">
  Bộ chọn giọng nói. Truyền tên giọng dựng sẵn như `nova`, giọng Gemini như `Kore`, hoặc object như `{ "id": "voice-id" }` cho giọng tuỳ chỉnh tương thích.
</ParamField>

<ParamField body="voice_id" type="string">
  Bộ chọn giọng native của provider cho các model speech tương thích MiniMax.
</ParamField>

<ParamField body="instructions" type="string">
  Chỉ dẫn style hoặc cách đọc tuỳ chọn cho các model TTS tương thích OpenAI có hỗ trợ.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt style nói tuỳ chọn cho model Gemini TTS.
</ParamField>

<ParamField body="language_code" type="string">
  Mã ngôn ngữ tuỳ chọn, ví dụ `en-US`, cho các route Gemini, xAI và TTS tương thích.
</ParamField>

<ParamField body="response_format" type="string">
  Định dạng audio. Giá trị phổ biến gồm `mp3`, `opus`, `aac`, `flac`, `wav`, và `pcm`; giá trị được hỗ trợ khác nhau theo họ model.
</ParamField>

<ParamField body="stream_format" type="string" default="audio">
  Định dạng trả về của TokenLab: `audio` hoặc `sse`. `stream_format=sse` không được hỗ trợ cho `tts-1` hoặc `tts-1-hd`.
</ParamField>

<ParamField body="speed" type="number">
  Tốc độ nói cho các họ model có hỗ trợ (0.25 đến 4.0).
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature cho các route TTS tương thích Gemini (0 đến 2).
</ParamField>

## Phản hồi

Trả về tệp audio theo định dạng đã yêu cầu.

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

## Mẫu giọng nói

| Voice     | Mô tả                            |
| --------- | -------------------------------- |
| `alloy`   | Trung tính, cân bằng             |
| `ash`     | Điềm tĩnh, chuẩn mực             |
| `ballad`  | Du dương, giàu biểu cảm          |
| `coral`   | Ấm áp, cuốn hút                  |
| `echo`    | Ấm áp, mang tính hội thoại       |
| `fable`   | Giàu biểu cảm, phù hợp kể chuyện |
| `nova`    | Thân thiện, rõ ràng              |
| `onyx`    | Trầm, uy quyền                   |
| `sage`    | Uyên bác, sâu sắc                |
| `shimmer` | Mềm mại, dịu dàng                |
| `verse`   | Năng động, linh hoạt             |

## Ví dụ phản hồi

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

## Trường quan trọng

<ResponseField name="Content-Type" type="string">Loại event hoặc message do API trả về.</ResponseField>
<ResponseField name="body" type="binary">Nội dung phản hồi thô. Lưu trực tiếp, không parse như JSON.</ResponseField>