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

将指定文本合成为音频文件。
## 接口描述 {#677ab7d5}
此 API 用于将指定文本内容合成为自然流畅的音频，同步返回合成的音频文件，适用于有声书合成、智能客服语音、音视频配音等场景。合成音频文件之前，可以先调用[查看音色列表](https://docs.coze.cn/developer_guides/list_voices) API，查看所有可用音色。
:::notice 注意
调用语音合成 API 会产生**语音合成费用**，具体费用详情请参考[音视频费用](https://docs.coze.cn/coze_pro/asr_tts_fee#b7ced22d)。
:::
## 基础信息 {#基础信息}
<!-- @cols-width: 180,680 -->
| | | \
|**请求方式** |POST |
|---|---|
| | | \
|**请求地址** |```Plain Text |\
| |https://api.coze.cn/v1/audio/speech |\
| |``` |\
| | |
| | | \
|**权限** |`createSpeech` |\
| |确保调用该接口使用的个人令牌开通了 `createSpeech` 权限，详细信息参考[鉴权方式](https://docs.coze.cn/developer_guides/authentication)。 |
| | | \
|**接口说明** |将指定文本合成为音频文件。 |

## 请求参数 {#请求参数}
### Header {#Header}
<!-- @cols-width: 144,165,551 -->
| | | | \
|**参数** |**取值** |**说明** |
|---|---|---|
| | | | \
|Authorization |Bearer $Access_Token |用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考[准备工作](https://docs.coze.cn/developer_guides/preparation)。 |
| | | | \
|Content-Type |application/json |解释请求正文的方式。 |

### Body {#Body}
<!-- @cols-width: 167,121,86,164,308 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|input |String |必选 |今天天气怎么样 |合成语音的文本，经由 UTF-8 编码。长度限制为 1024 字节。 |
| | | | | | \
|voice_id |String |必选 |742894******** |音频文件使用的音色 ID。 |\
| | | | |调用[查看音色列表](https://docs.coze.cn/developer_guides/list_voices) API，可查看所有可用音色。 |
| | | | | | \
|emotion |String |可选 |happy |设置多情感音色的情感类型，仅当 `voice_id` 为多情感音色时才支持设置情感类型。不同音色支持的情感范围不同，可以通过[系统音色列表](https://docs.coze.cn/dev_how_to_guides/sys_voice)查看各音色支持的情感。默认为空。枚举值如下： |\
| | | | | |\
| | | | |* `happy`：开心。 |\
| | | | |* `sad`：悲伤。 |\
| | | | |* `angry`：愤怒。 |\
| | | | |* `surprised`：惊讶。 |\
| | | | |* `fear`：恐惧。 |\
| | | | |* `hate`：厌恶。 |\
| | | | |* `excited`：兴奋。 |\
| | | | |* `coldness`：冷漠。 |\
| | | | |* `neutral`：中性。 |
| | | | | | \
|emotion_scale |Double |可选 |3 |情感值用于量化情感的强度。数值越高，情感表达越强烈，例如： “开心” 的情感值 5 比 1 更显兴奋。 |\
| | | | |取值范围：1.0~5.0，默认值：4.0。 |
| | | | | | \
|response_format |String |可选 |mp3 |音频文件的编码格式，支持设置为： |\
| | | | | |\
| | | | |* wav：返回二进制 wav 音频。 |\
| | | | |* pcm：返回二进制 pcm 音频。 |\
| | | | |* ogg_opus：返回多段含 opus 压缩分片音频。 |\
| | | | |* mp3：（默认）返回二进制 mp3 音频。 |
| | | | | | \
|speed |Double |可选 |1 |语速，大模型音色的取值范围为 0.5~2，小模型音色的取值范围为 0.2~3，通常保留一位小数即可。 |\
| | | | |其中 0.2 表示 0.2 倍速，3 表示 3 倍速。默认为 1，表示 1 倍速。 |
| | | | | | \
|sample_rate |Integer |可选 |24000 |音频采样率，单位为 Hz。 |\
| | | | | |\
| | | | |* 8000：8k |\
| | | | |* 16000：16k |\
| | | | |* 22050：22.05k |\
| | | | |* 24000：（默认）24k |\
| | | | |* 32000：32k |\
| | | | |* 44100：44.1k |\
| | | | |* 48000：48k |
| | | | | | \
|loudness_rate |Integer |可选 |30 |音频输出音量的增益或衰减比例，以百分比形式表示。取值范围为 `-50` ~ `100`，默认值为 0，表示原始音量。 |\
| | | | | |\
| | | | |* 负值表示衰减：`-50` 表示音量降低 50%（即 0.5 倍）。 |\
| | | | |* 正值表示增益：`100`表示音量提升 100%（即 2 倍）。 |
| | | | | | \
|context_texts |String |可选 |用低沉沙哑的语气、带着沧桑与绝望地说 |语音合成的辅助信息，用于控制合成语音的整体情绪（如悲伤、生气）、方言（如四川话、北京话）、语气（如撒娇、暧昧、吵架、夹子音）、语速（快慢）及音调（高低）等。 |\
| | | | |默认为空。 |\
| | | | |:::tip 说明 |\
| | | | |* 仅当 `voice_id` 为豆包语音合成大模型 2.0 音色时才支持该参数，具体音色列表请参见[系统音色列表](https://docs.coze.cn/dev_how_to_guides/sys_voice)。 |\
| | | | |* 更多关于豆包语音合成 2.0 的 `context_texts` 示例和效果可参考[语音指令-示例库](https://www.volcengine.com/docs/6561/1871062?lang=zh#_1-2-%F0%9F%92%A1%E8%AF%AD%E9%9F%B3%E6%8C%87%E4%BB%A4-%E7%A4%BA%E4%BE%8B%E5%BA%93)。 |\
| | | | |::: |


## 返回参数 {#返回参数}
如果成功调用此 API，接口会直接返回语音文件的内容。
## 示例 {#示例}
### 请求示例 {#请求示例}
```JSON
curl --location --request POST 'https://api.coze.cn/v1/audio/speech' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json' \
-d '{
  "input": "你好呀",
  "voice_id": "742894*********",
  "response_format": "wav"
}' 
--output speech.wav
```

### 返回示例 {#返回示例}
无
## 错误码 {#错误码}
如果调用此 API 失败，返回信息中包含 code 和 msg 字段。其中 code 为非 0 的错误码，表示接口调用失败；msg 字段中包含详细错误信息，你可以参考[错误码](https://docs.coze.cn/developer_guides/coze_error_codes)文档查看对应的解决方法。