Skip to main content

CosyVoice HTTP API

CosyVoice 的 HTTP 非即時語音合成介面，包含非串流和 SSE 串流呼叫、請求參數及回應欄位。

介面位址

將 YOUR_WORKSPACE_ID 替換為對應地區的業務空間 ID，並使用同地區的 API Key。
  • 華北 2（北京）
POST https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

請求標頭

參數類型必選說明
Authorizationstring必選驗證權杖，格式為 Bearer <your_api_key>。
Content-Typestring必選固定為 application/json。
X-DashScope-SSEstring可選串流輸出時設定為 enable；未設定時傳回完整結果。

呼叫範例

  • 非串流
  • 串流
curl -X POST "https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cosyvoice-v3-flash",
  "input": {
    "text": "我家的后面有一个很大的花园。",
    "voice": "longanyang",
    "format": "wav",
    "sample_rate": 24000
  }
}'
SSE 事件可能包含多行 data:。合併同一事件的所有 data: 行後解析 JSON；將音訊區塊按事件順序 Base64 解碼並串接。結束幀的 output.finish_reason 為 stop，並傳回完整音訊 URL。

請求主體

參數類型必選預設值說明
modelstring必選—語音合成模型 ID。支援模型與地區請參見非即時語音合成。
inputobject必選—輸入參數物件。
input.textstring必選—待合成文字。使用 SSML 時同時設定 enable_ssml=true；LaTeX 輸入無需額外設定。支援範圍、標籤和語法請參見 SSML 與 LaTeX。
input.voicestring必選—音色 ID。系統音色參見音色清單；自訂音色透過聲音複製或聲音設計建立，並使用綁定的目標模型合成。
input.formatstring可選mp3音訊編碼格式。可選 mp3、pcm、wav、opus。
input.sample_rateinteger可選22050音訊取樣率（Hz）。可選 8000、12000、16000、22050、24000、44100、48000。format=opus 時僅支援 8000、12000、16000、24000、48000。
input.volumeinteger可選50音量，取值範圍 [0, 100]。
input.ratefloat可選1.0語速，取值範圍 [0.5, 2.0]。
input.bit_rateinteger可選32音訊位元率（kbps），取值範圍 [6, 510]；僅在 format=opus 時生效。
input.pitchfloat可選1.0音調，取值範圍 [0.5, 2.0]。
input.enable_ssmlboolean可選—是否啟用 SSML。模型、音色和介面限制請參見使用限制。
input.word_timestamp_enabledboolean可選false是否傳回字級時間戳記，僅用於串流輸出。支援 cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 的複製音色，以及音色清單中標記支援的系統音色。其他模型的複製音色不支援。
input.seedinteger可選0隨機種子，取值範圍 [0, 65535]。模型版本、文字、音色和其他參數相同時，使用相同 seed 可重現相同合成結果。
input.language_hintsarray[string]可選—合成目標語言，目前僅處理陣列的第一個元素。此參數與複製樣本的來源語言無關。數字、縮寫、符號或小語種發音不符合預期時可設定，語言代碼見下方清單。複製來源語言參見聲音複製 API。
input.instructionstring可選—控制方言、情感或角色等合成效果的指令。適用模型、音色與寫法參見指令控制。
input.enable_aigc_tagboolean可選false是否在 WAV、MP3、Opus 音訊中嵌入 AIGC 隱性標識。僅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支援。
input.aigc_propagatorstring可選阿里雲 UID隱性標識的 ContentPropagator 欄位，用於標識傳播者；僅在 enable_aigc_tag=true 時生效。僅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支援。
input.aigc_propagate_idstring可選本次請求的 Request ID隱性標識的 PropagateID 欄位，用於標識本次傳播行為；僅在 enable_aigc_tag=true 時生效。僅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支援。
input.hot_fixobject可選—文字熱修復。pronunciation 自訂指定詞語的發音，replace 在合成前替換指定文字。cosyvoice-v2 不支援。
input.enable_markdown_filterboolean可選false是否在合成前過濾 Markdown 標記。僅 cosyvoice-v3-flash 的複製音色支援。

語言代碼

  • zh：中文
  • en：英語
  • fr：法語
  • de：德語
  • ja：日語
  • ko：韓語
  • ru：俄語
  • pt：葡萄牙語
  • th：泰語
  • id：印尼語
  • vi：越南語
  • es：西班牙語
  • it：義大利語
  • ms：馬來語
  • fil：菲律賓語
  • ar：阿拉伯語
文字熱修復設定範例： 
{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}

回應主體

參數類型說明
request_idstring本次請求的唯一識別碼。
outputobject模型輸出物件。
output.finish_reasonstring任務停止原因。null 表示合成中，stop 表示合成結束。
output.typestring僅串流輸出傳回。sentence-begin 表示句子開始；sentence-synthesis 表示音訊區塊，同一句可包含多個區塊；sentence-end 表示句子結束並傳回用量資訊。音訊區塊與資料幀一一對應，按順序附加至同一檔案。
output.original_textstring使用者輸入文字切分後的句子內容；最後一句可能沒有此欄位。
output.sentenceobject句子資訊。
output.sentence.indexinteger句子編號，從 0 開始。
output.sentence.wordsarray句子中的字及其時間戳記資訊。
output.sentence.words[].textstring字。
output.sentence.words[].begin_indexinteger字在句子中的開始位置，從 0 開始。
output.sentence.words[].end_indexinteger字在句子中的結束位置，從 1 開始。
output.sentence.words[].begin_timeinteger字對應音訊的開始時間戳記（毫秒）。
output.sentence.words[].end_timeinteger字對應音訊的結束時間戳記（毫秒）。
output.audioobject合成音訊物件。
output.audio.datastring串流輸出的 Base64 音訊區塊；非串流輸出時為空。
output.audio.urlstring完整音訊檔案的 URL，有效期 24 小時。
output.audio.idstring合成音訊的識別碼。
output.audio.expires_atintegerurl 的到期時間戳記。
usageobject用量資訊。
usage.charactersinteger累計計費字元數。
  • 非串流
  • 串流
{
  "output": {
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570,
      "url": "https://example.com/output.wav"
    },
    "finish_reason": "stop"
  },
  "usage": {
    "characters": 27
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}