扣子

扣子扣子编程扣子罗盘资源

文档反馈

低代码项目

快速开始

智能体

工作流

应用

资源

发布

模型

多人协作

开发工具

Coze CLI

API 参考

鉴权

智能体和应用

工作空间

文件夹

企业/组织

会话与消息

对话

工作流

文件

智能音视频

ASR、TTS 与音色

RTC 语音

WebSocket 语音

声纹识别

知识库

数据库

插件

变量

渠道

用量限额

账单与权益

回调

错误码

API 教程

API 常见问题

SDK 参考

音视频

推广与变现

常见问题

语音合成

更新于: 2026-06-25 19:29:14

将指定文本合成为音频文件。

接口描述

此 API 用于将指定文本内容合成为自然流畅的音频，同步返回合成的音频文件，适用于有声书合成、智能客服语音、音视频配音等场景。合成音频文件之前，可以先调用查看音色列表 API，查看所有可用音色。

注意

调用语音合成 API 会产生语音合成费用，具体费用详情请参考音视频费用。

基础信息

请求方式	POST
请求地址	`https://api.coze.cn/v1/audio/speech`
权限	`createSpeech` 确保调用该接口使用的个人令牌开通了 `createSpeech` 权限，详细信息参考鉴权方式。
接口说明	将指定文本合成为音频文件。

请求参数

参数	取值	说明
Authorization	Bearer $Access_Token	用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	解释请求正文的方式。

Body

参数	类型	是否必选	示例	说明
input	String	必选	今天天气怎么样	合成语音的文本，经由 UTF-8 编码。长度限制为 1024 字节。
voice_id	String	必选	742894********	音频文件使用的音色 ID。调用查看音色列表 API，可查看所有可用音色。
emotion	String	可选	happy	设置多情感音色的情感类型，仅当 `voice_id` 为多情感音色时才支持设置情感类型。不同音色支持的情感范围不同，可以通过系统音色列表查看各音色支持的情感。默认为空。枚举值如下： `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	可选	用低沉沙哑的语气、带着沧桑与绝望地说	语音合成的辅助信息，用于控制合成语音的整体情绪（如悲伤、生气）、方言（如四川话、北京话）、语气（如撒娇、暧昧、吵架、夹子音）、语速（快慢）及音调（高低）等。默认为空。说明仅当 `voice_id` 为豆包语音合成大模型 2.0 音色时才支持该参数，具体音色列表请参见系统音色列表。更多关于豆包语音合成 2.0 的 `context_texts` 示例和效果可参考语音指令-示例库。

返回参数

如果成功调用此 API，接口会直接返回语音文件的内容。

示例

请求示例

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 字段中包含详细错误信息，你可以参考错误码文档查看对应的解决方法。