語音合成 API 參考
統一的文字轉語音介面:預設返回 JSON(音訊位址、用量與計費明細),也可依 OpenAI 相容方式直接取得音訊二進位。適配 OpenAI TTS、百煉 Qwen-Audio-TTS 等語音合成模型。
注意: 預設返回 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 等欄位。
建立語音合成
POST
https://token.easyapi.com/v1/audio/speech把 input 文字合成為音訊。預設返回 JSON(audio.url 或 audio.data、usage、billing);Accept: application/octet-stream 或 audio/* 時返回音訊位元組。目前不支援句子級串流:即使傳入 stream_format=sse,也按單次完整音訊返回。
請求參數
| 名稱 | 位置 | 類型 | 必選 | 說明 |
|---|---|---|---|---|
Authorization | header | string | 是 | EasyAPI API Key。格式:Bearer `API_KEY` |
Content-Type | header | string | 是 | 固定 application/json |
Accept | string | 否 | 缺省或 application/json:返回結構化 JSON(預設);application/octet-stream 或 audio/*:返回音訊二進位 |
請求體
| 名稱 | 類型 | 必選 | 說明 |
|---|---|---|---|
model | string | 是 | 語音合成模型 ID,例如 qwen-audio-3.0-tts-plus、tts-1 |
input | string | 是 | 待合成文字,支援 SSML / LaTeX(需模型支援) |
voice | string | 是 | 音色,取值隨模型不同;百煉預設 longanhuan_v3.6 |
response_format | string | 否 | 音訊編碼格式:mp3(預設)、wav、pcm、opus |
speed | number | 否 | 語速倍率,百煉映射為 rate(0.5–2.0),超出範圍按邊界鉗制 |
instructions | string | 否 | 合成指令,用於控制方言、情感或角色等效果(百煉映射為 instruction) |
metadata | object | 否 | 上游原生參數透傳: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": "用轻松自然的语气朗读"
}返回欄位說明
| 名稱 | 類型 | 說明 |
|---|---|---|
id | string | 本次請求 ID,與回應標頭 X-EasyAPI-Request-Id 一致 |
object | string | 固定為 audio.speech |
created | integer | 回應產生時間(Unix 秒) |
model | string | 請求的模型 ID |
voice | string | 本次使用的音色 |
audio.storage | string | qiniu:已轉存七牛,見 audio.url;inline:內聯 base64,見 audio.data |
audio.format | string | 音訊編碼格式 |
audio.content_type | string | 音訊 MIME 類型 |
audio.sample_rate | integer | 音訊取樣率(Hz,未知時不返回) |
audio.bytes | integer | 音訊位元組數 |
audio.duration_seconds | number | 音訊時長(秒,解析失敗時為 0) |
audio.url | string | audio.storage=qiniu 時的七牛 CDN 位址 |
audio.data | string | audio.storage=inline 時的 base64 音訊資料 |
usage.characters | integer | 上游按字元計費時的計費字元數(百煉 3.0 系列) |
usage.input_tokens | integer | 計費輸入 Token;無字元口徑時退回上游 input_tokens 或本地估算 |
usage.output_tokens | integer | 計費輸出(音訊)Token;上游回傳 output_tokens 時優先使用 |
usage.total_tokens | integer | 輸入與輸出 Token 之和 |
usage.input_source | string | 輸入用量來源:upstream 或 local_estimate |
usage.output_source | string | 輸出用量來源:upstream、duration_estimate 或 bytes_estimate |
billing.mode | string | 計費模式:tiered_expr(表達式)、ratio(倍率)或 price(按次) |
billing.currency | string | 金額幣種,目前固定 USD |
billing.quota | integer | 本次實際扣減額度(500000 = 1 USD) |
billing.amount | number | quota 折算的金額(USD) |
billing.quota_per_unit | number | 額度換算比例(每 1 USD 的 quota) |
billing.group_ratio | number | 本次生效的分組倍率 |
billing.discount | number | 本次生效的折扣乘數(0~1) |
billing.model_ratio | number | ratio 模式:模型倍率 |
billing.model_price | number | price 模式:按次價格 |
billing.audio_ratio | number | ratio 模式:音訊輸入倍率 |
billing.audio_completion_ratio | number | ratio 模式:音訊輸出倍率 |
billing.matched_tier | string | tiered_expr 模式:命中的檔位名 |
billing.expression | string | tiered_expr 模式:本次計費表達式原文 |
billing.expression_cost | number | tiered_expr 模式:表達式求值結果(折算額度前) |
billing.cost_multiplier | number | tiered_expr 模式:峰谷等成本乘數 |
billing.inputs | object | tiered_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 為白名單欄位,不含渠道等內部資訊。