> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-f533effe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 文本转语音

> 使用 Venice 文本转语音模型从文本生成语音音频，选择模型对应的音色，并从 /audio/speech 端点保存二进制响应。

文本转语音可将书面文本合成为语音音频。选择一个 TTS 模型，选择该模型支持的音色，将文本发送到 `/audio/speech`，然后保存二进制的音频响应。

本指南适用于标准的语音生成。如果你希望使用自定义参考音色来生成语音，请参阅 [语音克隆](/guides/media/voice-cloning)。

## 基本用法

<CodeGroup>
  ```python Python theme={null}
  import os
  from pathlib import Path

  import requests

  response = requests.post(
      "https://api.venice.ai/api/v1/audio/speech",
      headers={
          "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "tts-kokoro",
          "voice": "af_sky",
          "input": "Hello, welcome to Venice Voice.",
      },
  )

  response.raise_for_status()
  Path("speech.mp3").write_bytes(response.content)
  ```

  ```javascript Node.js theme={null}
  import { writeFile } from "node:fs/promises";

  const response = await fetch("https://api.venice.ai/api/v1/audio/speech", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "tts-kokoro",
      voice: "af_sky",
      input: "Hello, welcome to Venice Voice.",
    }),
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));
  ```

  ```bash cURL theme={null}
  curl https://api.venice.ai/api/v1/audio/speech \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "tts-kokoro",
      "voice": "af_sky",
      "input": "Hello, welcome to Venice Voice."
    }' \
    --output speech.mp3
  ```
</CodeGroup>

成功响应的主体是模型默认格式的二进制音频，而非 JSON。`tts-kokoro` 目前默认为 MP3。

## 选择模型和音色

音色是模型专属的。`voice` 的值必须对所选的 `model` 有效。

请在 [文本转语音模型](/models/text-to-speech) 页面浏览可用的模型和音色。音色选择器中列出了在请求中需要传入的确切音色 ID。

<Note>
  音色 ID 区分大小写。切换 TTS 模型时，请同时更新 `voice` 的值。
</Note>

## 请求结构

| 参数                | 类型     | 是否必填 | 说明                                                              |
| ----------------- | ------ | ---- | --------------------------------------------------------------- |
| `model`           | string | 是    | 文本转语音模型 ID。                                                     |
| `voice`           | string | 是    | 所选模型支持的音色 ID。                                                   |
| `input`           | string | 是    | 需要合成的文本，最多 4096 个字符。                                            |
| `response_format` | string | 否    | 请求的输出格式：`mp3`、`opus`、`aac`、`flac`、`wav` 或 `pcm`。支持的格式和默认值因模型而异。 |

## 输出格式

你可以省略 `response_format` 以使用模型的默认格式。在选择文件扩展名或覆盖格式之前，请通过 Models API 查询该模型当前的 `default_format` 和 `supported_formats`：

```bash theme={null}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY" |
  jq '.data[] | select(.id == "tts-kokoro") | .model_spec | {default_format, supported_formats}'
```

响应的 `Content-Type` 标识返回的音频格式。请求所选模型不支持的格式会返回 HTTP `400`。

## 生产环境建议

* 当源文本和音色会被重复使用时，缓存生成的音频。
* 合成前对文本进行规范化和校对。标点符号会影响节奏和语调。
* 存储输出时请使用与模型响应格式相符的文件扩展名。

## 相关资源

<Tip>
  需要朗读比几句话更长的内容？[使用文本转语音朗读文章](/guides/media/article-narration) 涵盖 4096 字符的输入上限、按句子边界切分文本、将各片段拼接为一个音频文件，以及用于交互式播放的流式传输。
</Tip>

* [Audio Speech API](/api-reference/endpoint/audio/speech)
* [文本转语音模型](/models/text-to-speech)
* [使用文本转语音朗读文章](/guides/media/article-narration)
* [语音克隆指南](/guides/media/voice-cloning)