智能语音交互非流式语音合成HTTP API-智能语音交互(ISI)-阿里云帮助中心

功能介绍

非流式合成：提交文本后，返回合成音频文件的 URL，可通过该地址下载音频。
音色选择：通过音色名选择发音人。也可以使用参考音频进行合成，具体用法见下方场景示例。

前提条件

已准备项目 Appkey，详情请参见创建项目。
已获取 NLS Token，详情请参见获取Token。
已开通语音合成-语音合成服务，详情请参见开通服务。

语音合成提供试用版和商用版，计费详情请参见计费项。将试用版升级为商用版的方法，请参见计费方式。

服务端点

北京地域的网关地址为 https://nls-gateway-cn-beijing.aliyuncs.com。请求方法与完整地址如下：

POST https://nls-gateway-cn-beijing.aliyuncs.com/rest/v1/general/SpeechSynthesizer?appkey={appkey}

示例代码

示例从环境变量 NLS_APP_KEY 和 NLS_TOKEN 读取 Appkey 和 NLS Token。Python 示例依赖 requests，可通过 pip install requests 安装。

cURL

curl -X POST "https://nls-gateway-cn-beijing.aliyuncs.com/rest/v1/general/SpeechSynthesizer?appkey=${NLS_APP_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-NLS-Token: ${NLS_TOKEN}" \
  -d '{
    "text": "Hello, welcome to use our voice synthesis system.",
    "voice": "sarah"
  }'

对响应中的 data 字段再次进行 JSON 解析，获取其中的 url 后下载音频。

Python

import json
import os
from pathlib import Path

import requests

BASE_URL = "https://nls-gateway-cn-beijing.aliyuncs.com"
APPKEY = os.environ["NLS_APP_KEY"]
TOKEN = os.environ["NLS_TOKEN"]


def synthesize_audio(text, voice="sarah"):
    response = requests.post(
        f"{BASE_URL}/rest/v1/general/SpeechSynthesizer",
        params={"appkey": APPKEY},
        headers={"X-NLS-Token": TOKEN},
        json={"text": text, "voice": voice},
        timeout=120,
    )
    try:
        result = response.json()
    except ValueError:
        response.raise_for_status()
        raise RuntimeError("Unexpected non-JSON response")
    if response.status_code != 200 or result.get("error_code") != 0:
        raise RuntimeError(
            f"Synthesis failed: {result.get('error_code')} "
            f"{result.get('error_message')}; request_id={result.get('request_id')}"
        )

    audio_url = json.loads(result["data"])["url"]
    audio_response = requests.get(audio_url, timeout=60)
    audio_response.raise_for_status()
    Path("output.wav").write_bytes(audio_response.content)
    print("Audio saved to output.wav")


if __name__ == "__main__":
    synthesize_audio("Hello, welcome to use our voice synthesis system.")

场景示例：使用参考音频合成

以下 Python 示例通过 prompt_wav_url 指定参考音频，不传入 voice，将文本合成为音频并保存到本地。参考音频 URL 需能通过公网访问。返回结果的解析方式与指定音色的合成请求相同。

import json
import os
from pathlib import Path

import requests

BASE_URL = "https://nls-gateway-cn-beijing.aliyuncs.com"
APPKEY = os.environ["NLS_APP_KEY"]
TOKEN = os.environ["NLS_TOKEN"]


def synthesize_audio(text, prompt_wav_url):
    response = requests.post(
        f"{BASE_URL}/rest/v1/general/SpeechSynthesizer",
        params={"appkey": APPKEY},
        headers={"X-NLS-Token": TOKEN},
        json={"text": text, "prompt_wav_url": prompt_wav_url},
        timeout=120,
    )
    try:
        result = response.json()
    except ValueError:
        response.raise_for_status()
        raise RuntimeError("Unexpected non-JSON response")
    if response.status_code != 200 or result.get("error_code") != 0:
        raise RuntimeError(
            f"Synthesis failed: {result.get('error_code')} "
            f"{result.get('error_message')}; request_id={result.get('request_id')}"
        )

    audio_url = json.loads(result["data"])["url"]
    audio_response = requests.get(audio_url, timeout=60)
    audio_response.raise_for_status()
    Path("output.wav").write_bytes(audio_response.content)
    print("Audio saved to output.wav")


if __name__ == "__main__":
    synthesize_audio(
        "Hello, welcome to use our voice synthesis system.",
        "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/clone.wav",
    )

请求说明

请求头

参数	类型	是否必选	说明
Content-Type	String	是	请求体的媒体类型，固定为 `application/json`。
X-NLS-Token	String	是	NLS 服务访问 Token。

请求参数

参数	类型	是否必选	说明
appkey	String	是	项目 Appkey，通过控制台获取。

请求体

以下参数用于指定音色的合成请求。

参数	类型	是否必选	说明
text	String	是	待合成的文本，长度不超过 500 字符。
voice	String	是	发音人标识，取值请参见支持的音色列表。
format	String	否	音频输出格式，默认值为 `wav`。当前返回 WAV 音频，不支持通过此参数切换格式。如需其他格式，可在下载后转换。
sample_rate	Integer	否	音频采样率，单位为 Hz，默认值为 `24000`。当前返回 24000 Hz 音频，不支持通过此参数调整采样率。如需其他采样率，可在下载后重采样。

请求体示例：

{
    "text": "Hello, welcome to use our voice synthesis system.",
    "voice": "sarah",
    "format": "wav",
    "sample_rate": 24000
}

返回体

参数	类型	说明
status	Integer	HTTP 状态码，`200` 表示成功。
error_code	Integer	业务错误码，`0` 表示成功。
error_message	String	错误描述，成功时为空字符串。
request_id	String	请求唯一标识，用于排查问题。
data	String	成功时返回的合成结果，是需要二次 JSON 解析的字符串。
url	String	请求失败时返回的接口路径。

data 字段

参数	类型	说明
url	String	合成音频文件的下载地址，有效期为 24 小时，过期后需重新调用接口生成。

成功响应

以下示例中的音频地址已替换为占位地址。

{
    "status": 200,
    "data": "{\"url\":\"https://example.com/output.wav\"}",
    "request_id": "3f9667fbfc594d87ab1afa950647c5db",
    "error_code": 0,
    "error_message": ""
}

错误响应

未提供 Appkey 时，返回如下错误：

{
    "error_message": "Gateway:CLIENT_ERROR:Required String parameter 'appkey' is not present",
    "error_code": 40000000,
    "request_id": "b600c23af0ed4d43a7ce836b4fe59793",
    "url": "/rest/v1/general/SpeechSynthesizer",
    "status": 400
}

支持的音色列表

可用音色（voice）	说明
sarah	女声，美式英语
seline	女声，美式英语
megan	女声，英式英语
isabella	女声，英式英语
davis	男声，美式英语
michael	男声，美式英语
arthur	男声，英式英语
barry	男声，英式英语
sophie	女声，英式英语
grace	女声，英式英语
winston	男声，英式英语
edmund	男声，英式英语
paige	女声，美式英语
avery	女声，美式英语
hunter	男声，美式英语
mason	男声，美式英语

错误码

常见错误码及处理方法如下。

HTTP 状态码	error_code	说明	解决方案
400	40000000	请求缺少 Appkey 等参数错误，具体原因见 `error_message`。	检查 URL 中的 `appkey` 及请求参数。
400	40000001	Token 无效。	重新获取有效的 NLS Token。
500	50020003	未找到指定音色。	检查 `voice` 是否为本文支持的音色。
400	500	合成请求失败。	检查对应合成方式所需的参数。
500	50000000	服务端错误。	重试请求；持续出现时，保留 `request_id` 并联系技术支持。

其他 HTTP 错误的处理方法如下。

HTTP 状态码	解决方案
403	检查 Appkey 与 Token 是否匹配。
429	降低请求频率或申请提升配额。
503	稍后重试。

常见问题

音频文件链接的有效期是多久？

音频文件链接在生成后 24 小时内有效，过期后需重新调用接口生成。

文本长度有限制吗？

单次请求的文本长度不超过 500 字符。如果文本较长，建议分段合成。