> ## 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 speech는 `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 호환 speech 모델의 provider-native 음성 선택자입니다.
</ParamField>

<ParamField body="instructions" type="string">
  지원되는 OpenAI 호환 TTS 모델에 전달하는 선택적 스타일 또는 전달 지시입니다.
</ParamField>

<ParamField body="prompt" type="string">
  Gemini TTS 모델의 선택적 말하기 스타일 prompt입니다.
</ParamField>

<ParamField body="language_code" type="string">
  Gemini, xAI 및 호환 TTS route의 선택적 언어 코드입니다. 예: `en-US`.
</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 route의 샘플링 temperature입니다(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가 반환하는 event 또는 message type입니다.</ResponseField>
<ResponseField name="body" type="binary">원본 response body입니다. JSON으로 파싱하지 말고 그대로 저장하세요.</ResponseField>