語音合成 API 參考

語音合成 API 參考

統一的文字轉語音介面:預設返回 JSON(音訊位址、用量與計費明細),也可依 OpenAI 相容方式直接取得音訊二進位。適配 OpenAI TTS、百煉 Qwen-Audio-TTS 等語音合成模型。

欄位值
Base URLhttps://token.easyapi.com/v1
認證Authorization: Bearer `API_KEY`
範例模型qwen-audio-3.0-tts-plus
格式REST JSON(預設)/音訊二進位(Accept: application/octet-stream)
計費按輸入字元 / Token 與音訊用量計費,回應內含計費快照
注意: 預設返回 JSON:audio.storage=qiniu 時 audio.url 是平台轉存的七牛 CDN 位址(不暴露上游位址),七牛未啟用或轉存失敗時回退 audio.storage=inline 與 base64 的 audio.data。需要音訊位元組時在請求標頭加 Accept: application/octet-stream(OpenAI 官方 SDK 預設就會帶這個標頭),此時 Content-Type 由 response_format 決定:mp3 → audio/mpeg、wav → audio/wav、pcm → audio/pcm、opus → audio/ogg。stream_format=sse 時一律走二進位流。voice 取值隨模型而變:百煉 Qwen-Audio-TTS 的音色隨模型而變(qwen-audio-3.0-tts-plus 為 longanlingxin / longanlufeng,3.0-flash 為 longanhuan_v3.6 等),OpenAI TTS 使用 alloy / nova 等,請查閱對應模型的音色列表。模型特有的上游參數可放在 metadata 中透傳。

示例模型

下文均以 qwen-audio-3.0-tts-plus(Qwen Audio TTS Plus)為例;更換其他模型時,請替換 model 參數,並參考控制台模型說明調整 size、quality 等欄位。

建立語音合成

POSThttps://token.easyapi.com/v1/audio/speech

把 input 文字合成為音訊。預設返回 JSON(audio.url 或 audio.data、usage、billing);Accept: application/octet-stream 或 audio/* 時返回音訊位元組。目前不支援句子級串流:即使傳入 stream_format=sse,也按單次完整音訊返回。

請求參數

名稱位置類型必選說明
Authorizationheaderstring是EasyAPI API Key。格式:Bearer `API_KEY`
Content-Typeheaderstring是固定 application/json
Acceptstring否缺省或 application/json:返回結構化 JSON(預設);application/octet-stream 或 audio/*:返回音訊二進位

請求體

名稱類型必選說明
modelstring是語音合成模型 ID,例如 qwen-audio-3.0-tts-plus、tts-1
inputstring是待合成文字,支援 SSML / LaTeX(需模型支援)
voicestring是音色,取值隨模型不同;百煉預設 longanhuan_v3.6
response_formatstring否音訊編碼格式:mp3(預設)、wav、pcm、opus
speednumber否語速倍率,百煉映射為 rate(0.5–2.0),超出範圍按邊界鉗制
instructionsstring否合成指令,用於控制方言、情感或角色等效果(百煉映射為 instruction)
metadataobject否上游原生參數透傳:volume(0-100)、pitch(0.5-2.0)、bit_rate(6-510,僅 opus)、sample_rate、enable_ssml、word_timestamp_enabled、seed、language_hints、hot_fix、enable_aigc_tag;與標準欄位同名的鍵優先級最高

示例

{
  "model": "qwen-audio-3.0-tts-plus",
  "input": "你好,欢迎使用 EasyAPI 语音合成。",
  "voice": "longanlingxin",
  "response_format": "mp3",
  "speed": 1.0,
  "instructions": "用轻松自然的语气朗读"
}

返回欄位說明

名稱類型說明
idstring本次請求 ID,與回應標頭 X-EasyAPI-Request-Id 一致
objectstring固定為 audio.speech
createdinteger回應產生時間(Unix 秒)
modelstring請求的模型 ID
voicestring本次使用的音色
audio.storagestringqiniu:已轉存七牛,見 audio.url;inline:內聯 base64,見 audio.data
audio.formatstring音訊編碼格式
audio.content_typestring音訊 MIME 類型
audio.sample_rateinteger音訊取樣率(Hz,未知時不返回)
audio.bytesinteger音訊位元組數
audio.duration_secondsnumber音訊時長(秒,解析失敗時為 0)
audio.urlstringaudio.storage=qiniu 時的七牛 CDN 位址
audio.datastringaudio.storage=inline 時的 base64 音訊資料
usage.charactersinteger上游按字元計費時的計費字元數(百煉 3.0 系列)
usage.input_tokensinteger計費輸入 Token;無字元口徑時退回上游 input_tokens 或本地估算
usage.output_tokensinteger計費輸出(音訊)Token;上游回傳 output_tokens 時優先使用
usage.total_tokensinteger輸入與輸出 Token 之和
usage.input_sourcestring輸入用量來源:upstream 或 local_estimate
usage.output_sourcestring輸出用量來源:upstream、duration_estimate 或 bytes_estimate
billing.modestring計費模式:tiered_expr(表達式)、ratio(倍率)或 price(按次)
billing.currencystring金額幣種,目前固定 USD
billing.quotainteger本次實際扣減額度(500000 = 1 USD)
billing.amountnumberquota 折算的金額(USD)
billing.quota_per_unitnumber額度換算比例(每 1 USD 的 quota)
billing.group_rationumber本次生效的分組倍率
billing.discountnumber本次生效的折扣乘數(0~1)
billing.model_rationumberratio 模式:模型倍率
billing.model_pricenumberprice 模式:按次價格
billing.audio_rationumberratio 模式:音訊輸入倍率
billing.audio_completion_rationumberratio 模式:音訊輸出倍率
billing.matched_tierstringtiered_expr 模式:命中的檔位名
billing.expressionstringtiered_expr 模式:本次計費表達式原文
billing.expression_costnumbertiered_expr 模式:表達式求值結果(折算額度前)
billing.cost_multipliernumbertiered_expr 模式:峰谷等成本乘數
billing.inputsobjecttiered_expr 模式:表達式實際輸入變數,如 p、c、ai、ao、len

預設回應(JSON,七牛轉存)

{
  "id": "2026110206055130815495705874a1XipEBXYs",
  "object": "audio.speech",
  "created": 1793599552,
  "model": "qwen-audio-3.0-tts-plus",
  "voice": "longanlingxin",
  "audio": {
    "storage": "qiniu",
    "format": "mp3",
    "content_type": "audio/mpeg",
    "sample_rate": 24000,
    "bytes": 258048,
    "duration_seconds": 4.032,
    "url": "https://qiniu.easyapi.com/easyapi-ai/audio/2026/11/02/2026110206055130815495705874a1XipEBXYs.mp3"
  },
  "usage": {
    "characters": 15,
    "input_tokens": 15,
    "output_tokens": 67,
    "total_tokens": 82,
    "input_source": "upstream",
    "output_source": "duration_estimate"
  },
  "billing": {
    "mode": "tiered_expr",
    "currency": "USD",
    "quota": 79,
    "amount": 0.000158,
    "quota_per_unit": 500000,
    "group_ratio": 1,
    "discount": 0.5,
    "matched_tier": "speech",
    "expression": "tier(\"speech\", p * 20.9895)",
    "expression_cost": 314.8425,
    "cost_multiplier": 1,
    "inputs": { "p": 15, "c": 67, "ai": 0, "ao": 67, "len": 15 }
  }
}

二進位回應(Accept: application/octet-stream)

HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Length: 258048
X-EasyAPI-Audio-Bytes: 258048
X-EasyAPI-Audio-Seconds: 4.032
X-EasyAPI-Audio-Format: mp3
X-EasyAPI-Audio-Sample-Rate: 24000

<二进制音频数据>

返回結果

狀態碼狀態碼含義說明資料模型
200成功預設返回 JSON(audio.url 或 audio.data + usage + billing);Accept 為二進位類型時返回音訊位元組AudioSpeechResponse | audio/*
400請求錯誤參數不合法或上游拒絕,如音色不存在、文字為空ErrorResponse
401未認證權杖缺失或無效ErrorResponse
402額度不足帳戶餘額不足以支付本次合成ErrorResponse
429限流請求過於頻繁,請稍後重試ErrorResponse
500服務端錯誤上游或閘道異常,可重試ErrorResponse
響應: 計費口徑與後台使用日誌同源:billing.inputs 是表達式實際看到的變數,billing.quota 是最終扣減額度;billing 為白名單欄位,不含渠道等內部資訊。