Skip to main content

音訊產生 API 參考

使用 HTTPS 介面提交文字提示詞和參考音訊，以取得產生的音訊檔案。本文說明請求參數、回應結構和錯誤處理。

接入前準備

取得 API Key 和業務空間 ID，分別設定為環境變數 DASHSCOPE_API_KEY 和 SFM_WORKSPACE_ID。 請求方法為 HTTPS POST，端點如下，其中 {WorkspaceId} 為業務空間 ID： 
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

請求標頭

欄位必填說明
Authorization是Bearer <API Key>
Content-Type是application/json

呼叫範例

curl --request POST \
  "https://$SFM_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  --max-time 300 \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-audio-3.1-tts-next",
    "input": {
      "text_prompt": "一位女性清晰地说：“你好，欢迎使用。”",
      "format": "wav",
      "sample_rate": 48000,
      "channels": 2
    }
  }'
回應範例（ID 和下載地址已替換為示意值）： 
{
  "request_id": "example-request-id",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "data": "",
      "url": "https://example.com/generated.wav",
      "id": "audio_example-request-id",
      "expires_at": 1789616932,
      "duration": 1.12
    }
  },
  "usage": {
    "duration": 1
  }
}
使用實際回應中的 output.audio.url 下載檔案，URL 有效期為 24 小時。請勿使用上述示意地址下載。

請求參數

model 位於請求體頂層，其餘產生參數位於 input 物件內。
欄位類型必填預設值說明
modelstring是—模型 ID，請參閱支援的模型。
inputobject是—音訊產生輸入。
input.text_promptstring是—音訊描述或待合成文字。參考音訊按順序使用 @voice1、@voice2、@voice3 引用。長度上限請參閱模型表。
input.referencesarray否—參考音訊清單。未傳遞時僅使用文字產生。目前模型最多支援 3 條，每條最長 30 秒、不超過 10 MB。
input.references[].audio_urlstring條件必填—伺服器可存取的公開音訊 URL，與 audio_data 二選一。
input.references[].audio_datastring條件必填—音訊 data URI：data:{mime_type};base64,{base64_encoded_data}。與 audio_url 二選一。
input.formatstring否wav輸出格式：wav、mp3、pcm。不支援 Opus 輸出。
input.sample_rateinteger否48000輸出取樣率，單位 Hz：8000、16000、24000、44100、48000。
input.channelsinteger否2聲道數：1（單聲道）、2（雙聲道）。
input.volumeinteger否50音量，取值範圍 [0, 100]。
input.enable_cbrboolean否false僅 MP3 生效。true 為固定位元率（CBR），false 為可變位元率（VBR）。
input.bit_rateinteger否128僅 MP3 CBR 生效，單位 kbps。實際輸出受取樣率及 MP3 編碼檔位約束，詳見下表。
input.qualityinteger否5僅 MP3 VBR 生效。取值範圍 [0, 9]，0 為最高品質。
input.ratefloat否1.0語速，取值範圍 [0.5, 2.0]。
input.seedinteger否42請求層級隨機種子。
input.enable_aigc_tagboolean否false是否在產生音訊中新增 AIGC 識別浮水印。
參考音訊支援 WAV、MP3 和 OGG Opus，不支援裸 PCM。參考音訊格式與輸出格式是兩套限制：可以輸入 OGG Opus，但不能輸出 Opus。 參考音訊須透過 URL 或 Base64 提交，不支援使用系統音色或聲音複製音色 ID。

MP3 CBR 位元率

取樣率（Hz）輸出位元率下限（kbps）輸出位元率上限（kbps）
8000864
16000、240008160
44100、4800032320
位元率由取樣率和 MP3 編碼檔位共同決定。表中為輸出的位元率範圍，不表示支援區間內的任意整數；超出範圍的指定值會被限制在對應範圍內。

提交參考音訊

以下 Python 範例使用兩條參考音訊產生雙人對話。先安裝 requests，準備分別包含兩位說話人聲音、符合模型限制的 reference1.wav 和 reference2.wav，並設定前述環境變數。 references 按清單順序分配槽位：第一項 reference1.wav 對應 @voice1，第二項 reference2.wav 對應 @voice2。範例將兩條音訊分別編碼為 Base64，並在提示詞中引用對應說話人。 
import base64
import os
from pathlib import Path

import requests

reference1 = base64.b64encode(Path("reference1.wav").read_bytes()).decode("ascii")
reference2 = base64.b64encode(Path("reference2.wav").read_bytes()).decode("ascii")
workspace_id = os.environ["SFM_WORKSPACE_ID"]
endpoint = (
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com"
    "/api/v1/services/audio/tts/SpeechSynthesizer"
)
response = requests.post(
    endpoint,
    headers={
        "Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-audio-3.1-tts-next",
        "input": {
            "text_prompt": "@voice1 说：“今天阳光很好，一起去散步吧。”@voice2 回答：“好啊，我们去公园。”",
            "references": [
                {"audio_data": f"data:audio/wav;base64,{reference1}"},
                {"audio_data": f"data:audio/wav;base64,{reference2}"}
            ],
            "format": "wav",
        },
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()
audio_response = requests.get(result["output"]["audio"]["url"], timeout=60)
audio_response.raise_for_status()
Path("output.wav").write_bytes(audio_response.content)
使用 URL 時，將清單元素替換為 {"audio_url": "可公开访问的音频URL"}，不要同時填寫 audio_data。多人參考按清單順序編號，不能引用不存在的編號。

回應參數

欄位類型說明
request_idstring請求 ID，用於問題排查。
output.finish_reasonstring正常結束時為 "stop"。
output.audio.datastring此呼叫方式下為空字串；透過 output.audio.url 下載完整音訊。
output.audio.urlstring完整音訊檔案的下載 URL，有效期為 24 小時。
output.audio.idstring產生音訊的 ID。
output.audio.expires_atinteger下載 URL 的過期時間戳記。
output.audio.durationfloat產生音訊的時長，單位為秒。
usage.durationinteger本次產生音訊的時長，按秒四捨五入。此欄位不用於計算 Token 費用。
Podcast 場景單次最多產生 240 秒（4 分鐘）音訊，其他場景單次最多產生 120 秒。單價請參閱模型呼叫計費。

支援的模型

模型 IDPrompt 上限單次產生時長上限
qwen-audio-3.1-tts-next3000 字元Podcast：240 秒（4 分鐘）；其他場景：120 秒
場景、試聽與提示詞寫法請參閱音訊產生。本文範例使用表中的模型。

錯誤處理

錯誤回應範例： 
{
  "request_id": "example-request-id",
  "code": "CLIENT_ERROR",
  "message": "text_prompt exceeds the maximum length of 3000 characters."
}
HTTP 狀態碼code處理方式
400CLIENT_ERROR檢查 Prompt 長度、參考音訊數量與時長、URL/Base64 互斥關係、引用編號，以及是否使用了不支援的 voice 欄位。
404InvalidParameter若 message 為 "Model not exist."，請核對模型 ID、地域及目前帳號可用範圍。
401InvalidApiKey核對 API Key 是否有效。
403AccessDenied檢查模型呼叫權限。
429Throttling.RateQuota降低請求頻率。
400DataInspectionFailed檢查文字或參考音訊是否符合內容安全要求。
500InternalError保留 request_id，稍後重試或聯絡技術支援。