語(yǔ)音合成PRO版API接口開(kāi)發(fā)文檔（實(shí)時(shí)音頻流base64編碼）

一、接口概述

本接口為語(yǔ)音合成 PRO 版，支持基于實(shí)時(shí)音頻流的 base64 編碼輸出，可將傳入的文本內(nèi)容轉(zhuǎn)換為指定音色、格式的音頻，同時(shí)支持音量、語(yǔ)速、音調(diào)等參數(shù)自定義調(diào)整。接口關(guān)聯(lián) “聲音復(fù)刻 PRO” 和 “語(yǔ)音合成 PRO” 功能，適用于需要高質(zhì)量、個(gè)性化語(yǔ)音合成的場(chǎng)景，如智能語(yǔ)音交互、內(nèi)容播報(bào)、教育課件制作等。

二、資源訪問(wèn)情況提醒

結(jié)合歷史接口調(diào)用及資源測(cè)試經(jīng)驗(yàn)，使用本接口時(shí)需注意：

關(guān)聯(lián)的音頻相關(guān)資源（如通過(guò) “聲音復(fù)刻 PRO” 生成的音色對(duì)應(yīng)的音頻文件、合成后輸出的 MP3/WAV/PCM 格式音頻），若后續(xù)需通過(guò)其他接口（如視頻提取音頻接口）進(jìn)一步處理，需提前確認(rèn)資源鏈接的公開(kāi)可訪問(wèn)性，避免出現(xiàn) “非公開(kāi)視頻無(wú)法訪問(wèn)”“網(wǎng)頁(yè)解析失敗，可能是不支持的網(wǎng)頁(yè)類型” 等問(wèn)題。

若合成后的音頻需存儲(chǔ)或傳輸，建議檢查音頻鏈接格式兼容性，確保后續(xù)調(diào)用其他接口時(shí)可正常解析，減少因格式不支持導(dǎo)致的功能異常。

三、核心信息

（一）接口地址

https://#/api/ai/audiotaskpro

（二）返回格式

application/json

（三）請(qǐng)求方式

支持 HTTP GET / POST 兩種請(qǐng)求方式

（四）關(guān)聯(lián) API

聲音復(fù)刻 PRO：用于生成自定義音色 ID，該 ID 需作為本接口 “voice” 參數(shù)的值傳入，實(shí)現(xiàn)個(gè)性化語(yǔ)音合成。

語(yǔ)音合成 PRO：本接口為語(yǔ)音合成 PRO 功能的具體實(shí)現(xiàn)接口，提供更靈活的參數(shù)配置與實(shí)時(shí)音頻流輸出能力。

四、計(jì)費(fèi)說(shuō)明

字符統(tǒng)計(jì)規(guī)則：1 個(gè)中文字符計(jì)為 2 字符；1 個(gè)英文字母、1 個(gè)標(biāo)點(diǎn)符號(hào)（如逗號(hào)、句號(hào)、問(wèn)號(hào)等）、1 個(gè)句子中間的空格，均計(jì)為 1 字符。

注意事項(xiàng)：?jiǎn)未握?qǐng)求的文本內(nèi)容需控制在 2000 字符以內(nèi)，避免因超出字符限制導(dǎo)致請(qǐng)求失敗，具體計(jì)費(fèi)以控制臺(tái)實(shí)際統(tǒng)計(jì)為準(zhǔn)。

五、請(qǐng)求配置

（一）請(qǐng)求頭（HEADER）

名稱值

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

（二）請(qǐng)求參數(shù)

名稱必填類型示例值說(shuō)明

key是string35kj5jnlj53453kl5j43nj5接口密鑰，需在控制臺(tái) -> 密鑰管理頁(yè)面查看獲取，作為接口訪問(wèn)的身份憑證

text是string我像小草一樣在發(fā)芽。待合成的文本內(nèi)容，單次請(qǐng)求不超過(guò) 2000 字符；需使用中文符號(hào)；支持識(shí)別中小學(xué)常見(jiàn)數(shù)學(xué)表達(dá)式（含基礎(chǔ)運(yùn)算、代數(shù)、幾何等）

voice是stringvoice-c0c835a0b2714d1b9c4a10203edf857e音色 ID，需通過(guò) “聲音復(fù)刻 PRO” 接口返回獲?。灰部墒褂孟到y(tǒng)自帶音色 ID（詳見(jiàn)下文 “系統(tǒng)自帶音色 ID” 表）

format否stringmp3流式輸出音頻格式，默認(rèn)值為 mp3；支持 mp3、wav、pcm 三種格式

sample_rate否string22050輸出音頻采樣率，支持選項(xiàng)：8000（8kHz）、16000（16kHz）、22050（22.05kHz）、24000（24kHz）、44100（44.1kHz）、48000（48kHz）；默認(rèn)值可參考接口內(nèi)部配置

volume否string50音量調(diào)整，取值范圍 0～100，默認(rèn)值為 50；值越大音量越高

rate否string1.0語(yǔ)速調(diào)整，取值范圍 0.5～2，默認(rèn)值為 1.0；值越小語(yǔ)速越慢，值越大語(yǔ)速越快

pitch否string1.0音調(diào)調(diào)整，取值范圍 0.5～2，默認(rèn)值為 1.0；值越小音調(diào)越低，值越大音調(diào)越高

（三）系統(tǒng)自帶音色 ID

音色 ID名稱場(chǎng)景

voice-9cd3f01a272e4bbc901952f54bf37c1e猴哥網(wǎng)絡(luò)男聲

（四）請(qǐng)求示例

GET 請(qǐng)求示例

https://#/api/ai/audiotaskpro?key=35kj5jnlj53453kl5j43nj5&text=我像小草一樣在發(fā)芽。&voice=voice-c0c835a0b2714d1b9c4a10203edf857e&format=mp3&sample_rate=22050&volume=50&rate=1.0&pitch=1.0

POST 請(qǐng)求示例

請(qǐng)求體按application/x-www-form-urlencoded格式拼接參數(shù)：

key=35kj5jnlj53453kl5j43nj5&text=我像小草一樣在發(fā)芽。&voice=voice-c0c835a0b2714d1b9c4a10203edf857e&format=mp3&sample_rate=22050&volume=50&rate=1.0&pitch=1.0

六、返回?cái)?shù)據(jù)說(shuō)明

（一）返回參數(shù)

名稱類型說(shuō)明

statusstring請(qǐng)求狀態(tài)，成功時(shí)返回 "success"

codeint狀態(tài)碼（200 表示請(qǐng)求成功，其他為異常）

messagestring狀態(tài)信息，成功時(shí)返回 "語(yǔ)音合成成功"

request_paramsobject本次請(qǐng)求的參數(shù)詳情，含傳入的 text、voice、format 等參數(shù)

task_infoobject任務(wù)信息，包含任務(wù) ID（task_id），可用于后續(xù)任務(wù)狀態(tài)查詢、結(jié)果追溯

dataobject合成結(jié)果數(shù)據(jù)集，含 base64 編碼的音頻數(shù)據(jù)及音頻大小

audio_base64string實(shí)時(shí)音頻流的 base64 編碼字符串，可解碼為對(duì)應(yīng)的音頻文件

audio_sizeint音頻文件大?。▎挝唬鹤止?jié)）

debugstring/array調(diào)試數(shù)據(jù)（僅異常時(shí)返回，用于定位問(wèn)題，如參數(shù)錯(cuò)誤、密鑰無(wú)效等）

（二）返回示例（成功）

{

? "status": "success",

? "code": 200,

? "message": "語(yǔ)音合成成功",

? "request_params": {

? ? "text": "你好！",

? ? "voice": "voice-c0c835a0b2714d1b9c4a10203edf857e",

? ? "model": "v3pro",

? ? "format": "mp3",

? ? "sample_rate": 22050,

? ? "volume": 50,

? ? "rate": 1,

? ? "pitch": 1

? },

? "task_info": {

? ? "task_id": "1349271713ce3b73000c82d067808454"

? },

? "data": {

? ? "audio_base64": "SUQzAwAAAAA",

? ? "audio_size": 12211

? }

}

（三）常見(jiàn)狀態(tài)碼說(shuō)明

200：請(qǐng)求成功，已完成語(yǔ)音合成，可從data.audio_base64獲取音頻的 base64 編碼，從task_info.task_id獲取任務(wù) ID。

400：參數(shù)錯(cuò)誤，常見(jiàn)原因包括：text為空或超出 2000 字符限制、voice格式無(wú)效或未通過(guò) “聲音復(fù)刻 PRO” 獲取、format/sample_rate為不支持的取值；可通過(guò)message字段查看具體錯(cuò)誤提示。

401：權(quán)限驗(yàn)證失敗，如key無(wú)效、過(guò)期或未在控制臺(tái)完成配置；需重新獲取有效密鑰并檢查密鑰權(quán)限。

500+：服務(wù)端錯(cuò)誤，可能因接口服務(wù)異常、資源加載失敗等導(dǎo)致；可通過(guò)debug字段查看調(diào)試信息，或稍后重試接口。

七、開(kāi)發(fā)注意事項(xiàng)

文本內(nèi)容規(guī)范：text參數(shù)需使用中文符號(hào)（如中文逗號(hào) “，”、句號(hào) “?！保?，避免使用英文符號(hào)導(dǎo)致合成結(jié)果異常；若包含數(shù)學(xué)表達(dá)式，需確保為中小學(xué)常見(jiàn)類型（如 “2+3=5”“三角形面積 = 底 × 高 ÷2”），復(fù)雜表達(dá)式可能影響識(shí)別與合成效果。

音色 ID 有效性：使用自定義音色時(shí)，需確保voice參數(shù)的值為 “聲音復(fù)刻 PRO” 接口返回的有效 ID，且未被注銷或過(guò)期；使用系統(tǒng)自帶音色時(shí)，需確認(rèn)音色 ID 與接口文檔一致，避免因 ID 錯(cuò)誤導(dǎo)致音色異常。

音頻編碼處理：data.audio_base64為 base64 編碼的音頻流，開(kāi)發(fā)時(shí)需正確解碼（如使用 Python 的 base64 模塊、JavaScript 的 atob () 函數(shù)等），并按format參數(shù)指定的格式保存為音頻文件，避免解碼錯(cuò)誤導(dǎo)致文件損壞。

參數(shù)取值范圍：volume（0～100）、rate（0.5～2）、pitch（0.5～2）需嚴(yán)格遵守取值范圍，超出范圍可能導(dǎo)致接口返回異常；建議在開(kāi)發(fā)時(shí)增加參數(shù)校驗(yàn)邏輯，確保傳入值符合要求。

密鑰安全保護(hù)：key為接口訪問(wèn)的核心憑證，禁止在前端代碼（如 JavaScript）、公開(kāi)文檔、日志中明文存儲(chǔ)或泄露；若懷疑密鑰泄露，需立即在控制臺(tái)重置密鑰，防止接口被非法調(diào)用導(dǎo)致額外計(jì)費(fèi)或數(shù)據(jù)安全風(fēng)險(xiǎn)。

異常處理機(jī)制：若接口返回非 200 狀態(tài)碼，需優(yōu)先根據(jù)message和debug字段排查問(wèn)題；對(duì)于網(wǎng)絡(luò)波動(dòng)、服務(wù)臨時(shí)不可用的情況，建議實(shí)現(xiàn)重試機(jī)制（重試間隔建議設(shè)置為 3～5 秒，避免頻繁重試給服務(wù)端造成壓力）。

計(jì)費(fèi)成本控制：由于接口按字符計(jì)費(fèi)，開(kāi)發(fā)時(shí)需在前端或后端對(duì)text參數(shù)的字符數(shù)進(jìn)行統(tǒng)計(jì)（按計(jì)費(fèi)規(guī)則計(jì)算），確保單次請(qǐng)求不超過(guò) 2000 字符；同時(shí)避免重復(fù)發(fā)送相同文本的請(qǐng)求，減少不必要的計(jì)費(fèi)消耗。

來(lái)源：酷虎云api開(kāi)放平臺(tái)