HTTP API-智能语音交互(ISI)-阿里云帮助中心

本服务通过HTTP POST接口调用 fun-realtime-tts-preview 模型将文本转换为语音，返回合成音频的下载地址，适用于有声读物、课件配音、内容生产等场景。

功能介绍

非流式模式：HTTP POST提交请求，返回合成音频文件的URL，可直接下载。
音色选择：本模型支持多个可用音色，可通过音色名进行切换。

前提条件

已准备项目Appkey，详情请参见创建项目。
已获取Access Token，详情请参见获取Token概述。
服务开通，您需要开通语音合成-语音合成 服务，方可调用本接口，详情请参考开通服务。
- 语音合成提供试用版和商用版两种计费模式，详情请参见试用版和商用版。如果您需要将试用版升级为商用版，请参见试用版升级为商用版。

服务端点

服务地域与对应的网关地址：

北京地域：https://nls-gateway-cn-beijing.aliyuncs.com

请求的协议和完整地址：

POST {gateway_url}/rest/v1/general/SpeechSynthesizer?appkey={appkey}

请求头

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

请求参数（URL Query）

参数	类型	是否必选	说明
appkey	String	是	应用Key，通过管控台获取。

请求体

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

text string （必选）

待合成的文本内容。

最大长度不超过500字符。

voice string （必选）

发音人标识。可选值请参见下方支持的音色列表。

format string （可选）

音频输出格式。

默认值：wav。

取值范围：

sample_rate integer （可选）

音频采样率（Hz）。

默认值：24000。

取值范围：

16000
24000
48000

支持的音色列表

可用音色（voice）	说明
sarah	女声，美式英语
seline	女声，美式英语
mary	女声，英式英语
charlotte	女声，英式英语
john	男声，美式英语
michael	男声，美式英语
davis	男声，美式英语
arthur	男声，英式英语
barry	男声，英式英语

返回体	成功响应 `{ "status": 200, "message": "SUCCESS", "request_id": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "data": "{\"url\":\"https://xxx.oss-cn-xxx.aliyuncs.com/xxx.wav\",\"duration\":3200}" }` 错误响应 `{ "status": 400, "message": "Parameter 'voice' is invalid.", "request_id": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "data": null }`
status `integer` HTTP状态码。200表示成功。
message `string` 状态描述信息。
request_id `string` 请求唯一标识，用于排查问题。
data `string` JSON字符串，包含合成结果，需二次JSON解析。属性 url `string` 合成音频文件的下载地址。有效期为24小时，过期后需重新调用接口生成。 duration `integer` 音频时长（毫秒）。

错误码

HTTP状态码	错误码（code）	说明	解决方案
400	InvalidParameter	请求参数不合法。	检查text、voice等参数是否正确。
401	Unauthorized	Token无效或已过期。	重新获取NLS Token。
403	Forbidden	无权限访问该资源。	检查appkey与Token是否匹配。
429	TooManyRequests	请求频率超限。	降低请求频率或申请提升配额。
500	InternalError	服务内部错误。	重试请求，如持续出现请联系技术支持。
503	ServiceUnavailable	服务暂不可用。	稍后重试。

示例代码

以下示例演示如何通过接口调用实现语音合成，获取音频文件URL。

cURL

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

Python

import requests
import json

# API配置
BASE_URL = 'https://nls-gateway-cn-beijing.aliyuncs.com'
API_TOKEN = 'd929f54****'  # 替换为您的NLS Token
APPKEY = 'tts-appkey'

def synthesize_audio(text, voice='sarah'):
    """非流式语音合成"""
    url = f"{BASE_URL}/rest/v1/general/SpeechSynthesizer"
    headers = {
        "Content-Type": "application/json",
        "X-NLS-Token": API_TOKEN
    }
    params = {
        "appkey": APPKEY
    }
    data = {
        "text": text,
        "voice": voice
    }
    response = requests.post(url, headers=headers, json=data, params=params)
    response.raise_for_status()

    # 解析响应
    resp_json = response.json()
    result = json.loads(resp_json['data'])
    audio_url = result.get('url')
    if audio_url:
        # 下载音频文件
        audio_response = requests.get(audio_url)
        with open("output.wav", "wb") as f:
            f.write(audio_response.content)
        print(f"音频文件已保存: output.wav")
    else:
        print(f"合成失败: {resp_json.get('message')}")

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

常见问题

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

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

Q：文本长度有限制吗？

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