文本语音合成

接口标识: aitexttospeech 价格: 0.001 元/次 VIP免费异步响应

接口介绍
接口文档
在线测试

接口简介

文本语音合成接口把一段文字转成自然人声，单次最多 2000 字符，可从音色列表挑选音色，并用最长 100 字符的自然语言指令描述语气，也可在文本里嵌入情感标签控制情绪。语速与音调可在 0.5~2.0 倍间调节，输出 mp3、wav 或 pcm，采样率 8000Hz~44100Hz 五档，固定随机种子可复现同一段音频。每分钟语音约 10~20 秒生成，适合有声读物、课程讲解、语音播报与客服外呼。【调用约定】本接口为任务类：返回的 task_id 需调用 taskresult 查询终态结果（output_status 为 finish 或 fail）；status 为 not 或 processing 时请每隔5-10秒重复查询直至终态。

详细介绍

![文本语音合成接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261109/apiops_aitexttospeech__1794169264_8b0a701931b5.png)

想把一段文字变成可以播放的语音，却不想自己录音？把文本和选定的音色ID交给接口，合成好的自然语音以音频文件地址返回。

## 接口概述

文本语音合成接口面向智能客服、有声阅读、内容播报、营销配音等场景：传入待合成的文本与音色ID，由阿里云百炼语音大模型完成合成，默认使用 qwen-audio-3.0-tts-flash，可在后台切换。支持在文本中嵌入情感标签、通过自然语言指令控制语调语速情感，并提供语速、音调、随机种子、输出格式与采样率等参数。接口为异步任务模式：提交后立即返回任务ID，合成在后台完成，调用方通过 taskresult 任务查询接口获取音频下载地址，链接有效期以任务结果的 output_msg 提示为准。

## 核心能力

1. **文本转语音**：输入 content 文本（最大2000字符）与 voice 音色ID即可合成自然语音，输出 mp3（默认）/wav/pcm 格式，采样率支持 8000/16000/22050/24000/44100Hz。
2. **情感标签**：在文本中嵌入方括号标签即可控制情绪表现，如 [excited] 兴奋、[whispers] 耳语、[laughing] 大笑，让语音有起伏。
3. **自然语言指令**：instruction 传入不超过100字符的指令，如「用温柔的语气，语速稍慢」「播报新闻，语气严肃专业」，直接描述想要的效果。
4. **细粒度参数**：rate 语速与 pitch 音调（取值均为 [0.5, 2.0]，默认 1.0），seed 随机种子（取值 0~65535），相同参数配合相同 seed 可复现相近结果。
5. **模型可切换**：默认使用 qwen-audio-3.0-tts-flash，可在后台切换绑定的语音合成模型。

## 产品优势

- **接入简单**：POST 提交 + JSON 返回，配合任务查询接口取结果，无需自建 TTS 引擎与录音棚。
- **异步不阻塞**：提交即返回任务ID，合成在后台完成，长文本也不拖住调用方连接。

## 效果展示

一句话理解：它就像把一份标注好情绪提示的稿件交给配音员——选定声线、写好要求，录好的音频文件直接交回给你。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| content | 大家好，欢迎收听本期产品介绍。[excited] 今天我们带来三个重点更新。 | 待合成文本，最大 2000 字符，可嵌入情感标签 |
| voice | longanhuan_v3.6 | 音色 ID，必传，参见音色列表 |
| instruction | 用亲切自然的语气播报，语速适中 | 自然语言指令，控制音调/语速/情感，最大 100 字符 |
| format | mp3 | 音频格式：mp3（默认）/wav/pcm |
| sample_rate | 24000 | 采样率（Hz）：8000/16000/22050/24000/44100，默认 24000 |

你会拿到的结果（凭 task_id 经 taskresult 查询，output_status=finish 时）：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 任务状态 | finish | `output_status`（not/processing/finish/fail） |
| 音频下载地址 | https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/4f/c7/20261112/9e2d41ab.mp3 | `output_dourl`，临时链接，过期时间随 output_msg 返回 |
| 合成音色 | longanhuan_v3.6 | `output_info.voice` |
| 音频格式 | mp3 | `output_info.format` |
| 采样率 | 24000 | `output_info.sample_rate` |
| 合成字符数 | 38 | `output_info.char_count` |
| 上游请求ID | 7d4f2a91-3c5e-8b6a-0d2f-4e6a8c1b3d5f | `output_info.request_id`，排查问题时可提供 |
| 任务耗时 | 6 | `output_time`（秒） |

API请求示例：

```
POST /api/v1/aitexttospeech
content=大家好，欢迎收听本期产品介绍。[excited] 今天我们带来三个重点更新。&voice=longanhuan_v3.6&instruction=用亲切自然的语气播报，语速适中&format=mp3&sample_rate=24000
```

提交后返回 task_id，凭它调用任务查询接口轮询，output_status=finish 即完成：

```
POST /api/v1/taskresult
task_id=ac8k3fq2m7xwzr4yn1t6
```

API响应示例（taskresult 查回的最终异步结果）：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "task_id": "ac8k3fq2m7xwzr4yn1t6",
    "serialnumber": "ac8k3fq2m7xwzr4yn1t6",
    "jk_mark": "aitexttospeech",
    "output_status": "finish",
    "output_content": "",
    "output_dourl": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/4f/c7/20261112/9e2d41ab.mp3",
    "output_info": {
      "voice": "longanhuan_v3.6",
      "format": "mp3",
      "sample_rate": 24000,
      "char_count": 38,
      "request_id": "7d4f2a91-3c5e-8b6a-0d2f-4e6a8c1b3d5f"
    },
    "output_msg": "语音合成完成，共 38 字符，下载 URL（output_dourl）过期时间：2026-11-13 10:35:21。",
    "output_time": 6
  }
}
```

解读：finish 时 output_dourl 即合成音频的下载地址，它是上游生成的临时链接（有效期 24 小时，不经平台转存），具体过期时间在 output_msg 中给出，请及时下载；fail 时 output_msg 给出原因。本接口 serialnumber 固定与 task_id 相同。

## 应用场景

- **智能客服播报**：把答复话术合成为语音，用于电话客服、语音助手与 IVR 播报。
- **有声内容制作**：文章、小说、课件转成有声读物，情感标签让叙述更有表现力。
- **营销与直播配音**：活动口播、商品介绍、短视频旁白快速产出，无需预约录音。
- **无障碍与工具朗读**：为视障用户或阅读工具提供网页与文档的语音朗读能力。

## 应用案例

- **在线教育公司**：把课程讲义批量合成为音频课件，按课程编号提交任务，凭 task_id 逐一查询下载，配音环节从按小时计费的录音外包变成接口调用。
- **智能硬件厂商**：设备端提示语通过接口预合成入库，指令控制统一口吻，不同批次语音风格保持一致。
- **自媒体工作室**：图文内容转视频时用固定音色加情感标签生成旁白，seed 固定后系列视频声线稳定，观众听感连贯。

常见问题

Q：接口是同步还是异步？如何获取合成结果？

A：异步任务接口。提交成功返回 task_id、serialnumber 与 task_msg，随后通过 taskresult 接口凭 task_id 查询：output_status 表示任务状态（not=未开始 / processing=处理中 / finish=完成 / fail=失败），完成后 output_dourl 即合成音频的下载地址。

Q：合成语音必须传哪些参数？

A：content（待合成文本，最大2000字符）与 voice（音色ID）为必填；format 默认 mp3，可选 wav/pcm；sample_rate 默认 24000，可选 8000/16000/22050/44100。

Q：情感标签和指令控制怎么用？

A：在 content 中嵌入方括号标签即可改变情绪表现，如 [excited] 表示兴奋、[whispers] 表示耳语；instruction 参数传不超过100字符的自然语言指令，直接描述想要的语调语速情感，如「用温柔的语气，语速稍慢」。

Q：音频下载地址的有效期是多久？

A：output_dourl 为临时下载地址，过期时间在任务结果的 output_msg 中返回，请在任务完成后及时下载或转存到自己的存储中。

Q：serialnumber 和 task_id 是什么关系？

A：本接口提交响应中的 serialnumber 与 task_id 相同，查询任务结果统一凭 task_id 通过 taskresult 接口进行。

Q：seed 参数有什么用？

A：seed 为随机种子，取值 0~65535。按表内声明，相同参数配合相同 seed 可复现相近的合成结果，便于系列化配音时保持音色表现稳定。

文本语音合成 TTS 文字转语音语音合成多音色情感标签智能配音

接口地址： https://www.phpwc.cn/api/aitexttospeech

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`content`	string	必填	-	要合成语音的文本内容（最大2000字符），支持嵌入情感标签如[excited]
`voice`	string	必填	-	音色ID，参见音色列表（如longanlingxin）
`instruction`	string	选填	-	自然语言指令，控制语音的音调、语速、情感（最大100字符）
`format`	string	选填	`mp3`	音频输出格式：mp3（默认）/wav/pcm
`sample_rate`	int	选填	`24000`	采样率（Hz）：8000/16000/22050/24000/44100
`rate`	float	选填	`1.0`	语速，默认1.0，取值范围[0.5, 2.0]
`pitch`	float	选填	`1.0`	音调，默认1.0，取值范围[0.5, 2.0]
`seed`	int	选填	`0`	随机种子，相同参数+相同seed可复现结果，取值范围[0, 65535]
`serialnumber`	string	选填	-	开发者自定义查询编号，同接口下不可重复，用于幂等和关联查询

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`task_id`	string	任务ID，用于通过 taskresult 接口查询任务结果
`serialnumber`	string	调用方传入的 serialnumber，用于通过 taskresult 接口查询任务结果
`task_msg`	string	预计任务耗时：每分钟语音约10~20秒
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

异步响应字段（调用 taskresult 返回）

本接口为异步任务类：提交后立即返回 task_id，需再调用 taskresult（传 task_id 或 serialnumber）查询结果，返回字段如下。

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	任务结果数据
`task_id`	string	任务ID（与提交响应一致）
`serialnumber`	string	调用方传入的 serialnumber（未传则为空串）
`jk_mark`	string	原调用接口标识
`output_status`	string	任务状态：not=未开始 / processing=处理中 / finish=完成 / fail=失败
`output_content`	string	完成后的文本结果（如翻译全文、问答答案），无则为空串
`output_dourl`	string	完成后的产物下载地址（图片/文档/音视频），无则为空串
`output_info`−	object	任务明细数据
`voice`	string	合成音色
`format`	string	音频格式（如 mp3）
`sample_rate`	int	采样率（Hz）
`char_count`	int	合成字符数
`request_id`	string	上游请求ID
`output_msg`	string	任务说明 / 状态提示文案
`output_time`	int	任务耗时（秒）
`request_id`	string	请求追踪ID

taskresult 响应 JSON 示例：

{
  "code": 0,
  "desc": "success",
  "data": {
    "task_id": "任务ID",
    "serialnumber": "调用方传入的流水号",
    "jk_mark": "aitexttospeech",
    "output_status": "finish",
    "output_content": "文本结果（无则空）",
    "output_dourl": "产物下载地址（无则空）",
    "output_info": { },
    "output_msg": "任务完成提示",
    "output_time": 12
  },
  "request_id": "abc123..."
}

请先登录后使用在线测试