本文介紹語音合成CosyVoice Java SDK的參數和介面細節。
如需使用“中國內地(北京)”地區的模型,請前往“中國內地(北京)”地區的API-KEY頁面
使用者指南:關於模型介紹和選型建議請參見即時語音合成-CosyVoice/Sambert。
前提條件
已開通服務並擷取API Key。請配置API Key到環境變數(準備下線,併入配置 API Key),而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。
說明當您需要為第三方應用或使用者提供臨時存取權限,或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時,建議使用臨時鑒權Token。
與長期有效 API Key 相比,臨時鑒權 Token 具備時效性短(60秒)、安全性高的特點,適用於臨時調用情境,能有效降低API Key泄露的風險。
使用方式:在代碼中,將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。
模型與價格
模型名稱 | 單價 | 免費額度(注) |
cosyvoice-v3-plus | $0.286706/萬字元 | 無免費額度 |
cosyvoice-v3-flash | $0.14335/萬字元 | |
cosyvoice-v2 | $0.286706/萬字元 |
語音合成文本限制與格式規範
文本長度限制
字元計算規則
漢字(包括簡/繁體漢字、日文漢字和韓文漢字)按2個字元計算,其他所有字元(如標點符號、字母、數字、日韓文假名/諺文等)均按 1個字元計算
計算文本長度時,不包含SSML 標籤內容
樣本:
"你好"→ 2(你)+2(好)=4字元"中A文123"→ 2(中)+1(A)+2(文)+1(1)+1(2)+1(3)=8字元"中文。"→ 2(中)+2(文)+1(。)=5字元"中 文。"→ 2(中)+1(空格)+2(文)+1(。)=6字元"<speak>你好</speak>"→ 2(你)+2(好)=4字元
編碼格式
需採用UTF-8編碼。
數學運算式支援說明
當前數學運算式解析功能僅適用於cosyvoice-v2、cosyvoice-v3-flash和cosyvoice-v3-plus模型,支援識別中小學常見的數學運算式,包括但不限於基礎運算、代數、幾何等內容。
詳情請參見LaTeX 方程式轉語音。
SSML標記語言支援說明
當前SSML(Speech Synthesis Markup Language,語音合成標記語言)功能僅適用於cosyvoice-v3-flash、cosyvoice-v3-plus和cosyvoice-v2模型的複刻音色,以及音色列表中標記為支援的系統音色,使用時需滿足以下條件:
使用DashScope SDK 2.20.3 或更高版本
僅支援非流式調用和單向流式調用(即SpeechSynthesizer類的
call方法),不支援雙向流式調用(即SpeechSynthesizer類的streamingCall方法)和Flowable調用。使用方法與普通語音合成一致:將包含SSML的文本傳入SpeechSynthesizer類的
call方法即可
快速開始
SpeechSynthesizer類提供了語音合成的關鍵介面,支援以下幾種調用方式:
非流式調用:阻塞式,一次性發送完整文本,直接返回完整音頻。適合短文本語音合成情境。
單向流式調用:非阻塞式,一次性發送完整文本,通過回呼函數接收音頻資料(可能分區)。適用於對即時性要求高的短文本語音合成情境。
雙向流式調用:非阻塞式,可分多次發送文本片段,通過回呼函數即時接收增量合成的音頻流。適合即時性要求高的長文本語音合成情境。
非流式調用
同步提交語音合成任務,直接擷取完整結果。
執行個體化SpeechSynthesizer類綁定請求參數,調用call方法進行合成並擷取二進位音頻資料。
發送的文本長度不得超過2000字元(詳情請參見SpeechSynthesizer類的call方法)。
每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。
單向流式調用
非同步提交語音合成任務,通過註冊ResultCallback回調,逐幀接收即時語音分段資料。
執行個體化SpeechSynthesizer類綁定請求參數和回調介面(ResultCallback),調用call方法進行合成並通過回調介面(ResultCallback)的onEvent方法即時擷取合成結果。
發送的文本長度不得超過2000字元(詳情請參見SpeechSynthesizer類的call方法)。
每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。
雙向流式調用
分多次提交文本,通過註冊ResultCallback回調,逐幀接收即時語音分段資料。
流式輸入時可多次調用
streamingCall按順序提交文本片段。服務端接收文本片段後自動進行分句:完整語句立即合成
不完整語句緩衝至完整後合成
調用
streamingComplete時,服務端會強制合成所有已接收但未處理的文本片段(包括未完成的句子)。發送文本片段的間隔不得超過23秒,否則觸發“request timeout after 23 seconds”異常。
若無待發送文本,需及時調用
streamingComplete結束任務。服務端強制設定23秒逾時機制,用戶端無法修改該配置。
執行個體化SpeechSynthesizer類
串流
多次調用SpeechSynthesizer類的
streamingCall方法分區提交待合成文本,將待合成文本分段發送至服務端。在發送文本的過程中,服務端會通過回調介面(ResultCallback)的
onEvent方法,將合成結果即時返回給用戶端。每次調用
streamingCall方法發送的文本片段(即text)長度不得超過2000字元,累計發送的文本總長度不得超過20萬字元。結束處理
調用SpeechSynthesizer類的
streamingComplete方法結束語音合成。該方法會阻塞當前線程,直到回調介面(ResultCallback)的
onComplete或者onError回調觸發後才會釋放線程阻塞。請務必確保調用該方法,否則可能會導致結尾部分的文本無法成功轉換為語音。
通過Flowable調用
Flowable是一個用於工作流程和商務程序管理的開源架構,它基於Apache 2.0許可證發布。關於Flowable的使用,請參見Flowable API詳情。
使用Flowable前需確保已整合RxJava庫,並瞭解響應式編程基礎概念。
單向流式調用
以下樣本展示了通過Flowable對象的blockingForEach介面,阻塞式地擷取每次流式返回的SpeechSynthesisResult類型資料。
您也可以在Flowable的所有流式資料返回完成後,通過SpeechSynthesizer類的getAudioData來擷取完整的合成結果。
雙向流式調用
以下樣本展示了通過Flowable對象作為輸入參數,輸入文字資料流。並通過Flowable對象作為傳回值,利用的blockingForEach介面,阻塞式地擷取每次流式返回的SpeechSynthesisResult類型資料。
您也可以在Flowable的所有流式資料返回完成後,通過SpeechSynthesizer類的getAudioData來擷取完整的合成結果。
高並發調用
在DashScope Java SDK中,採用了OkHttp3的串連池技術,以減少重複建立串連的開銷。詳情請參見高並發情境。
請求參數
通過SpeechSynthesisParam的鏈式方法配置模型、音色等參數。配置完成的參數對象傳入SpeechSynthesizer類的建構函式中使用。
參數 | 類型 | 是否必須 | 說明 |
model | String | 是 | 語音合成模型。 不同模型版本需要使用對應版本的音色:
|
voice | String | 是 | 語音合成所使用的音色。 支援系統音色和複刻音色:
|
format | enum | 否 | 音頻編碼格式及採樣率。 若未指定 說明 預設採樣率代表當前音色的最佳採樣率,預設條件下預設按照該採樣率輸出,同時支援降採樣或升採樣。 可指定的音頻編碼格式及採樣率如下:
|
volume | int | 否 | 音量。 預設值:50。 取值範圍:[0, 100]。50代表標準音量。音量大小與該值呈線性關係,0為靜音,100為最大音量。 |
speechRate | float | 否 | 語速。 預設值:1.0。 取值範圍:[0.5, 2.0]。1.0為標準語速,小於1.0則減慢,大於1.0則加快。 |
pitchRate | float | 否 | 音高。該值作為音高調節的乘數,但其與聽感上的音高變化並非嚴格的線性或對數關係,建議通過測試選擇合適的值。 預設值:1.0。 取值範圍:[0.5, 2.0]。1.0為音色自然音高。大於1.0則音高變高,小於1.0則音高變低。 |
bit_rate | int | 否 | 音頻碼率(單位kbps)。音頻格式為opus時,支援通過 預設值:32。 取值範圍:[6, 510]。 說明
通過parameter設定通過parameters設定 |
enableWordTimestamp | boolean | 否 | 是否開啟字層級時間戳記。 預設值:false。
該功能僅適用於cosyvoice-v3-flash、cosyvoice-v3-plus和cosyvoice-v2模型的複刻音色,以及音色列表中標記為支援的系統音色。 時間戳記結果僅能通過回調介面擷取 |
seed | int | 否 | 產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。 預設值0。 取值範圍:[0, 65535]。 |
languageHints | List | 否 | 指定語音合成的目標語言,提升合成效果。 當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:
取值範圍:
注意:此參數為數組,但目前的版本僅處理第一個元素,因此建議只傳入一個值。 重要 此參數用於指定語音合成的目標語言,該設定與聲音複刻時的樣本音訊語種無關。如果您需要設定複刻任務的源語言,請參見CosyVoice聲音複刻API。 |
instruction | String | 否 | 設定指令,用於控制方言、情感或角色等合成效果。該功能僅適用於cosyvoice-v3-flash模型的複刻音色,以及音色列表中標記為支援Instruct的系統音色。 使用要求:
支援的功能: |
enable_aigc_tag | boolean | 否 | 是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。 預設值:false。 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 說明
通過parameter設定通過parameters設定 |
aigc_propagator | String | 否 | 設定AIGC隱性標識中的 預設值:阿里雲UID。 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 說明
通過parameter設定通過parameters設定 |
aigc_propagate_id | String | 否 | 設定AIGC隱性標識中的 預設值:本次語音合成請求Request ID。 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 說明
通過parameter設定通過parameters設定 |
關鍵介面
SpeechSynthesizer類
SpeechSynthesizer通過“import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;”方式引入,提供語音合成的關鍵介面。
介面/方法 | 參數 | 傳回值 | 描述 |
|
|
| 建構函式。
|
|
|
| 將整段文本(無論是純文字還是包含SSML的文本)轉換為語音。 在建立
重要 每次調用 |
|
| 無 | 流式發送待合成文本(不支援包含SSML的文本)。 您可以多次調用該介面,將待合成文本分多次發送給服務端。合成結果通過回調介面(ResultCallback)的 詳細調用流程和參考樣本請參見雙向流式調用。 |
| 無 | 無 | 結束流式語音合成。 該方法阻塞調用線程直至發生以下條件之一:
詳細的調用流程和參考樣本請參見雙向流式調用。 重要 雙向流式調用時,請確保調用該方法,以免導致合成語音缺失。 |
|
| 合成結果,封裝在 | 非流式文本(不支援包含SSML的文本)輸入即時轉換為流式語音輸出,合成結果在flowable中流式返回。 詳細的調用流程和參考樣本請參見通過Flowable調用。 |
| code: WebSocket關閉碼(Close Code) reason:關閉原因 這兩個參數可參考The WebSocket Protocol文檔進行配置 | true | 在任務結束後,無論是否出現異常都需要關閉WebSocket串連,避免造成串連泄漏。關於如何複用串連提升效率請參考高並發情境。 |
|
| 合成結果,封裝在 | 流式文本(不支援包含SSML的文本)輸入即時轉換為流式語音輸出,合成結果在flowable中流式返回。 詳細的調用流程和參考樣本請參見通過Flowable調用。 |
| 無 | 上一個任務的Request ID | 擷取上一個任務的Request ID,在調用 |
| 無 | 當前任務首包延遲 | 擷取當前任務的首包延遲(一般在500ms左右),任務結束後使用。 首包延遲是開始發送文本和接收第一個音頻包之間的時間,單位為毫秒。 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時;若在高並發情境下複用串連,則不包含串連耗時。 |
回調介面(ResultCallback)
在單向流式調用或雙向流式調用時,通過回調介面ResultCallback擷取合成結果。通過“import com.alibaba.dashscope.common.ResultCallback;”方式引入。
介面/方法 | 參數 | 傳回值 | 描述 |
|
| 無 | 當服務端推送語音合成資料時被非同步回調。 調用SpeechSynthesisResult的 調用SpeechSynthesisResult的 |
| 無 | 無 | 當所有合成資料全部返回(語音合成完成)後被非同步回調。 |
|
| 無 | 發生異常時該介面被非同步回調。 建議在 |
響應結果
伺服器返回二進位音頻資料:
非流式調用:對SpeechSynthesizer類的
call方法返回的二進位音頻資料進行處理。單向流式調用或雙向流式調用:對回調介面(ResultCallback)的
onEvent方法的參數(SpeechSynthesisResult類型)進行處理。SpeechSynthesisResult的關鍵介面如下:介面/方法
參數
傳回值
描述
public ByteBuffer getAudioFrame()無
二進位音頻資料
返回當前流式合成片段的二進位音頻資料,可能為空白(當無新資料到達時)。
您可以將二進位音頻資料合成為一個完整的音頻檔案後使用播放器播放,也可以通過支援流式播放的播放器即時播放。
重要流式語音合成中,對於mp3/opus等壓縮格式,音頻分段傳輸需使用流式播放器,不可逐幀播放,避免解碼失敗。
支援流式播放的播放器:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
將音頻資料合成完整的音頻檔案時,應以追加模式寫入同一檔案。
流式語音合成的wav/mp3 格式音頻僅首幀包含頭資訊,後續幀為純音頻資料。
public String getRequestId()無
任務的Request ID
擷取任務的Request ID。當調用
getAudioFrame擷取到二進位音頻資料時,getRequestId方法的傳回值為null。public SpeechSynthesisUsage getUsage()無
SpeechSynthesisUsage:截止當前,本次請求中計費的有效字元數返回
SpeechSynthesisUsage或null。通過
SpeechSynthesisUsage的getCharacters方法,可擷取截止當前,本次請求中計費的有效字元數,請以最後一次收到的SpeechSynthesisUsage為準。public Sentence getTimestamp()無
Sentence:截止當前,本次請求中計費的句子需要開啟
enableWordTimestamp字層級時間戳記返回
Sentence或null。Sentence的方法:getIndex:可擷取句子編號,從0開始。getWords:可擷取組成句子的字元數組List<Word>,請以最後一次收到的Sentence為準。
Word方法:getText:擷取字的文本。getBeginIndex:擷取字在句子中的開始位置索引,從 0 開始。getEndIndex:擷取字在句子中的結束位置索引,從 1 開始。getBeginTime:擷取字對應音訊開始時間戳,單位為毫秒。getEndTime:擷取字對應音訊結束時間戳記,單位為毫秒。
錯誤碼
如遇報錯問題,請參見錯誤資訊進行排查。
更多樣本
更多樣本,請參見GitHub。
常見問題
功能特性/計量計費/限流
Q:當遇到發音不準的情況時,有什麼解決方案可以嘗試?
通過SSML可以對語音合成效果進行個人化定製。
Q:語音合成是按文本字元數計費的,要如何查看或擷取每次合成的文本長度?
其他調用方式:通過響應結果SpeechSynthesisResult的
getUsage方法擷取。請以收到的最後一個響應結果為準。
故障排查
如遇代碼報錯問題,請根據錯誤碼中的資訊進行排查。
Q:如何擷取Request ID?
通過以下兩種方式可以擷取:
在回調介面(ResultCallback)的
onEvent方法中調用SpeechSynthesisResult的getRequestId方法。getRequestId方法傳回值可能為null,詳情請參見SpeechSynthesisResult中關於getRequestId方法的描述。調用SpeechSynthesizer的
getLastRequestId方法。
Q:使用SSML功能失敗是什麼原因?
請按以下步驟排查:
確保限制與約束正確
確保使用正確的介面:只有SpeechSynthesizer類的
call方法支援SSML確保待合成文本為純文字格式且符合格式要求,詳情請參見SSML標記語言介紹
Q:為什麼音頻無法播放?
請根據以下情境逐一排查:
音頻儲存為完整檔案(如xx.mp3)的情況
音頻格式一致性:確保請求參數中設定的音頻格式與檔案尾碼一致。例如,如果請求參數設定的音頻格式為wav,但檔案尾碼為mp3,可能會導致播放失敗。
播放器相容性:確認使用的播放器是否支援該音頻檔案的格式和採樣率。例如,某些播放器可能不支援高採樣率或特定編碼的音頻檔案。
流式播放音訊情況
將音頻流儲存為完整檔案,嘗試使用播放器播放。如果檔案無法播放,請參考情境 1 的排查方法。
如果檔案可以正常播放,則問題可能出在流式播放的實現上。請確認使用的播放器是否支援流式播放。
常見的支援流式播放的工具和庫包括:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
Q:為什麼音頻播放卡頓?
請根據以下情境逐一排查:
檢查文本發送速度: 確保發送文本的間隔合理,避免前一句音頻播放完畢後,下一句文本未能及時發送。
檢查回呼函數效能:
檢查回呼函數中是否存在過多商務邏輯,導致阻塞。
回呼函數運行在 WebSocket 線程中,若被阻塞,可能會影響 WebSocket 接收網路資料包,進而導致音頻接收卡頓。
建議將音頻資料寫入一個獨立的音頻緩衝區(audio buffer),然後在其他線程中讀取並處理,避免阻塞 WebSocket 線程。
檢查網路穩定性: 確保網路連接穩定,避免因網路波動導致音頻傳輸中斷或延遲。
Q:語音合成慢(合成時間長)是什麼原因?
請按以下步驟排查:
檢查輸入間隔
如果是流式語音合成,請確認文字發送間隔是否過長(如上段發出後延遲數秒才發送下段),過久間隔會導致合成總時間長度增加。
分析效能指標
首包延遲:正常500ms左右。
RTF(RTF = 合成總耗時/音頻時間長度):正常小於1.0。
Q:合成的語音發音錯誤如何處理?
請使用SSML的<phoneme>標籤指定正確的發音。
Q:為什麼沒有返回語音?為什麼結尾部分的文本沒能成功轉換成語音?(合成語音缺失)
請檢查是否遺漏了調用SpeechSynthesizer類的streamingComplete方法。在語音合成過程中,服務端會在緩衝足夠文本後才開始合成。如果未調用streamingComplete方法,可能會導致緩衝中的結尾部分文本未能被合成為語音。
許可權與認證
Q:我希望我的 API Key 僅用於 CosyVoice 語音合成服務,而不被百鍊其他模型使用(許可權隔離),我該如何做?
可以通過建立業務空間並只授權特定模型來限制API Key的使用範圍。詳情請參見業務空間管理。
更多問題
請參見GitHub QA。