全部產品
Search
文件中心

Intelligent Speech Interaction:介面說明

更新時間:Oct 28, 2026

語音合成為您提供將輸入文本合成為語音位元據的功能。本文檔介紹了目前的目錄下各SDK文檔的通用資訊。

功能介紹

  • 支援輸出PCM、WAV和MP3編碼格式資料。

  • 支援設定語速、語調和音量。

  • 支援一次性合成300字元以內的文字,其中1個漢字、1個英文字母、1個標點或1個句子中間空格均算作1個字元,超過300個字元的內容將會截斷。

  • 僅支援採用UTF-8編碼的文本輸入。

說明
  • 字層級音素邊界介面:語音合成服務在輸出音訊同時,可輸出每個漢字/英文單詞在音頻中的時間位置,即時間戳記。該時間資訊可用於驅動虛擬人口型、做視頻配音字幕等。詳情請參見語音合成時間戳記功能介紹。

服務地址

訪問類型

說明

URL

外網訪問

所有伺服器均可通過外網訪問URL調用服務。SDK預設使用該URL。

wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1

互動流程

語音合成 WebSocket 互動流程:用戶端發送 StartSynthesis 指令,服務端返迴音頻流和 SynthesisCompleted 事件。

說明
  • 上圖描述的是WebSocket的互動流程,關於RESTful API的互動流程圖請參見RESTful API。

  • 服務端的響應除了音頻流之外,都會在返回資訊的header包含本次識別任務的task_id參數,是本次請求的唯一標識。

  • 如果您希望即時播放服務端返回的音頻流,請使用支援流式播放的音頻播放器。支援流式播放的播放器包括:ffmpeg、pyaudio(Python)、AudioFormat(Java)和MediaSource(JavaScript)等。

  1. 鑒權

    用戶端與服務端建立WebSocket串連時,使用Token進行鑒權。

  2. 開始合成

    用戶端發起語音合成請求,在請求訊息中進行參數設定,各參數含義如下表所示。

    參數

    類型

    是否必需

    說明

    appkey

    String

    是

    管控台建立的專案Appkey。

    text

    String

    是

    待合成文本,常值內容必須採用UTF-8編碼,長度不超過300個字元(英文字母之間需要添加空格)。

    說明

    只有支援多情感的音色,才能使用<emotion>標籤,否則會報錯:Illegal ssml text。

    voice

    String

    否

    發音人,預設是xiaoyun。

    format

    String

    否

    音頻編碼格式,支援.pcm、.wav和.mp3格式。預設值:pcm。

    sample_rate

    Integer

    否

    音頻採樣率,預設值:16000 Hz。

    volume

    Integer

    否

    音量,取值範圍:0~100。預設值:50。

    speech_rate

    Integer

    否

    語速,取值範圍:-500~500,預設值:0。

    [-500, 0, 500] 對應的語速倍速區間為 [0.5, 1.0, 2.0]。

    1. -500表示預設語速的0.5倍速。

    2. 0表示預設語速的1倍速。1倍速是指模型預設輸出的合成語速,語速會依據每一個發音人略有不同,大概每秒鐘4個字左右。

    3. 500表示預設語速的2倍速。

    計算方法如下:

    1. 0.8倍速(1-1/0.8)/0.002 = -125

    2. 1.2倍速(1-1/1.2)/0.001 = 166

    說明
    1. 小於1倍速時,使用0.002係數。

    2. 大於1倍速時,使用0.001係數。

    實際演算法結果取近似值。

    pitch_rate

    Integer

    否

    語調,取值範圍:-500~500,預設值:0。

    enable_subtitle

    Boolean

    否

    開啟字層級時間戳記。更多使用方法,請參見語音合成時間戳記功能介紹。

  3. 接收合成資料

    服務端返回合成的語音位元據,SDK接收並處理位元據。

  4. 結束合成

    語音合成完畢,服務端發送合成完畢事件通知,舉例如下。

    {
        "header": {
            "message_id": "05450bf69c53413f8d88aed1ee60****",
            "task_id": "640bc797bb684bd6960185651307****",
            "namespace": "SpeechSynthesizer",
            "name": "SynthesisCompleted",
            "status": 20000000,
            "status_message": "GATEWAY|SUCCESS|Success."
        }
    }
    說明

    文檔樣本將合成的音頻儲存在檔案中,如果您需要播放音頻且對即時性要求較高,建議使用流式播放,即邊接收語音資料邊播放,減少延時。

  5. 合成失敗處理

    當因為參數或其他原因導致合成任務失敗時,會收到任務失敗(TaskFailed)通知,舉例如下。收到任務失敗通知後,對應底層串連將斷開。

    {
       "header":{
          "namespace":"Default",
          "name":"TaskFailed",
          "status":41020001,
          "message_id":"62c126f7d9b340deb82b5b7eaca0****",
          "task_id":"4552df26d1f547aab9a2c4a94678****",
          "status_text":"TTS:TtsClientError:[tts]Engine return error code: 418"
       }
    }

音色列表

名稱

voice參數值

類型

適用情境

支援語言

支援採樣率(Hz)

支援字層級音素邊界介面

備忘

小雲

Xiaoyun

標準女聲

通用情境

中文及中英文混合情境

8K/16K

否

無

小剛

Xiaogang

標準男聲

通用情境

中文及中英文混合情境

8K/16K

否

無

若兮

Ruoxi

溫柔女聲

通用情境

中文及中英文混合情境

8K/16K/24K

否

無

思琪

Siqi

溫柔女聲

通用情境

中文及中英文混合情境

8K/16K/24K

是

無

思佳

Sijia

標準女聲

通用情境

中文及中英文混合情境

8K/16K/24K

否

無

思誠

Sicheng

標準男聲

通用情境

中文及中英文混合情境

8K/16K/24K

是

無

艾琪

Aiqi

溫柔女聲

通用情境

中文及中英文混合情境

8K/16K

是

無

艾佳

Aijia

標準女聲

通用情境

中文及中英文混合情境

8K/16K

是

無

艾誠

Aicheng

標準男聲

通用情境

中文及中英文混合情境

8K/16K

是

無

艾達

Aida

標準男聲

通用情境

中文及中英文混合情境

8K/16K

是

無

寧兒

Ninger

標準女聲

通用情境

純中文情境

8K/16K/24K

否

無

瑞琳

Ruilin

標準女聲

通用情境

純中文情境

8K/16K/24K

否

無

思悅

Siyue

溫柔女聲

客服情境

中文及中英文混合情境

8K/16K/24K

是

無

艾雅

Aiya

嚴厲女聲

客服情境

中文及中英文混合情境

8K/16K

是

無

艾夏

Aixia

親和女聲

客服情境

中文及中英文混合情境

8K/16K

是

無

艾美

Aimei

甜美女聲

客服情境

中文及中英文混合情境

8K/16K

是

無

艾雨

Aiyu

自然女聲

客服情境

中文及中英文混合情境

8K/16K

是

無

艾悅

Aiyue

溫柔女聲

客服情境

中文及中英文混合情境

8K/16K

是

無

艾婧

Aijing

嚴厲女聲

客服情境

中文及中英文混合情境

8K/16K

是

無

小美

Xiaomei

甜美女聲

客服情境

中文及中英文混合情境

8K/16K/24K

否

無

艾娜

Aina

浙普女聲

客服情境

純中文情境

8K/16K

是

無

伊娜

Yina

浙普女聲

客服情境

純中文情境

8K/16K/24K

否

無

思婧

Sijing

嚴厲女聲

客服情境

純中文情境

8K/16K/24K

是

無

思彤

Sitong

兒童音

童聲情境

純中文情境

8K/16K/24K

否

無

小北

Xiaobei

蘿莉女聲

童聲情境

純中文情境

8K/16K/24K

是

無

艾彤

Aitong

兒童音

童聲情境

純中文情境

8K/16K

是

無

艾薇

Aiwei

蘿莉女聲

童聲情境

純中文情境

8K/16K

是

無

艾寶

Aibao

蘿莉女聲

童聲情境

純中文情境

8K/16K

是

無

Harry

Harry

英音男聲

英文情境

英文情境

8K/16K

否

無

Abby

Abby

美音女聲

英文情境

英文情境

8K/16K

否

無

Andy

Andy

美音男聲

英文情境

英文情境

8K/16K

否

無

Eric

Eric

英音男聲

英文情境

英文情境

8K/16K

否

無

Emily

Emily

英音女聲

英文情境

英文情境

8K/16K

否

無

Luna

Luna

英音女聲

英文情境

英文情境

8K/16K

否

無

Luca

Luca

英音男聲

英文情境

英文情境

8K/16K

否

無

Wendy

Wendy

英音女聲

英文情境

英文情境

8K/16K/24K

否

無

William

William

英音男聲

英文情境

英文情境

8K/16K/24K

否

無

Olivia

Olivia

英音女聲

英文情境

英文情境

8K/16K/24K

否

無

姍姍

Shanshan

粵語女聲

方言情境

標準粵文(簡體)及粵英文混合情境

8K/16K/24K

否

無

小玥

Xiaoyue

四川話女聲

方言情境

中文及中英文混合情境

8K/16K

否

公測版

Lydia

Lydia

英中雙語女聲

英文情境

英文情境

8K/16K

否

公測版

艾碩

Aishuo

自然男聲

客服情境

中文及中英文混合情境

8K/16K

是

公測版

青青

Qingqing

中國台灣話女聲

方言情境

中文情境

8K/16K

否

公測版

翠姐

Cuijie

東北話女聲

方言情境

中文情境

8K/16K

否

公測版

小澤

Xiaoze

湖南重口音男聲

方言情境

中文情境

8K/16K

是

公測版

服務狀態代碼

服務的每一次響應都包含status欄位,即服務狀態代碼,各狀態代碼含義如下。

通用錯誤:

錯誤碼

原因

解決辦法

40000001

身份認證失敗

檢查使用的令牌是否正確,是否到期。

40000002

無效的訊息

檢查發送的訊息是否符合要求。

403

令牌到期或無效的參數

首先檢查使用的令牌是否到期,然後檢查參數值設定是否合理。

40000004

空閑逾時

確認是否長時間(10秒)沒有發送資料到服務端。

40000005

請求數量過多

檢查是否超過了並發串連數或者每秒鐘請求數。如果超過並發數,建議從免費版升級到商用版,或者商用版擴容並發資源。

40000000

預設的用戶端錯誤碼

根據錯誤訊息解決問題,或提交工單。

50000000

預設的服務端錯誤

如果狀態代碼偶爾返回,可以忽略;如果狀態代碼多次返回,請提交工單。

50000001

內部調用錯誤

如果狀態代碼偶爾返回,可以忽略;如果狀態代碼多次返回,請提交工單。

網關錯誤:

錯誤碼

原因

解決辦法

40010001

不支援的介面

如果使用SDK,請提交工單。

40010002

不支援的指令

如果使用SDK,請提交工單。

40010003

無效的指令

如果使用SDK,請提交工單。

40010004

用戶端提前中斷連線

檢查是否在請求正常完成之前關閉了串連。

40010005

任務狀態錯誤

發送了當前任務狀態不能處理的指令。

配置錯誤:

錯誤碼

原因

解決辦法

40020105

應用不存在

檢查應用appkey是否正確,是否與令牌歸屬同一個帳號。

TTS(Text to Speech)錯誤:

錯誤碼

原因

解決辦法

41020001

參數錯誤

檢查是否傳遞了正確的參數。

51020001

TTS服務端錯誤

如果狀態代碼偶爾返回,可以忽略;如果狀態代碼多次返回,請提交工單。