語音合成 API

HopBase 的 MiniMax Speech 2.8 語音合成與其他模型共用同一 Base URL 與同一套 Authorization: Bearer sk-your-key 鑑權,沒有單獨的音訊網域或憑證。兩個語音模型屬於獨立分組 MiniMax 語音 官方直連,綁定對話或影片分組的金鑰調不到它們。

MiniMax Speech 2.8 把文字同步合成為音訊——回應就是音訊本身,沒有任務要輪詢。兩個入口共用 Base URL https://api.hop-base.com 與 Bearer 鑑權:OpenAI 相容的 POST /v1/audio/speech,可直接套用 OpenAI SDK;MiniMax 原生的 POST /v1/t2a_v2,提供完整參數與串流輸出。

模型 ID 區分大小寫、無別名,tts-1 / tts-1-hd 不會被識別。請使用已開通 MiniMax 語音 官方直連 分組的金鑰,並用 GET /v1/models 確認。

OpenAI 相容入口

POST /v1/audio/speech 接受 OpenAI 的請求結構,回應直接是音訊位元組。

不支援 stream_format,傳了回傳 400。回應 Content-Type 隨 response_format 分別為 audio/mpeg、audio/ogg、audio/flac、audio/wav、audio/pcm。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-turbo",
    "input": "你好,世界。",
    "voice": "Chinese (Mandarin)_News_Anchor",
    "response_format": "mp3"
  }' \
  --output hello.mp3

用官方 openai SDK 時,只需改 Base URL 與 model / voice 取值:

from openai import OpenAI

client = OpenAI(base_url="https://api.hop-base.com/v1", api_key="sk-your-key")

response = client.audio.speech.create(
    model="speech-2.8-turbo",
    voice="Chinese (Mandarin)_News_Anchor",
    input="你好,世界。",
    response_format="mp3",
)
response.write_to_file("hello.mp3")

# 長文字:邊收邊寫盤,不在記憶體裡累積整段音訊
with client.audio.speech.with_streaming_response.create(
    model="speech-2.8-turbo",
    voice="Chinese (Mandarin)_News_Anchor",
    input="這裡放一段較長的文案。",
) as streamed:
    streamed.stream_to_file("long.mp3")

原生入口

POST /v1/t2a_v2 原樣接受 MiniMax T2A v2 請求體:model、text(最長 10000 字元)、voice_setting(voice_id、speed、vol、pitch、emotion)、audio_setting(format、sample_rate、bitrate、channel)、language_boost、stream、stream_options 均原樣透傳——每個欄位與取值見下方請求參數。回應 JSON 也與官方結構一致:data.audio 是十六進位編碼的音訊,extra_info 帶 usage_characters 與音訊中繼資料。

• output_format 只支援 hex(預設),傳 url 回傳 400。
• voice_setting.speed 會被鉗到 0.5-2。
• audio_setting.format 為 "opus" 時必須顯式傳 sample_rate(如 24000),否則請求以參數錯誤失敗。
• stream: true 切換為 SSE:每個 data: {...} 事件帶一段音訊,末塊 data.status 為 2 並附 extra_info。預設末塊的 data.audio 是完整聚合音訊,可用 stream_options.exclude_aggregated_audio: true 關掉。

import requests

resp = requests.post(
    "https://api.hop-base.com/v1/t2a_v2",
    headers={"Authorization": "Bearer sk-your-key"},
    json={
        "model": "speech-2.8-hd",
        "text": "你好,世界",
        "voice_setting": {"voice_id": "Chinese (Mandarin)_News_Anchor", "speed": 1.0},
        "audio_setting": {"format": "mp3", "sample_rate": 32000},
    },
)
body = resp.json()
open("hello.mp3", "wb").write(bytes.fromhex(body["data"]["audio"]))
print(body["extra_info"]["usage_characters"])  # 計費字元數

串流:逐行讀 SSE 回應體,把每個 data: 事件裡的十六進位片段解碼後追加寫入檔案。請把 exclude_aggregated_audio 設為 true,這樣末塊(status 為 2)只帶 extra_info——否則末塊的 data.audio 會把整段音訊再發一遍,直接追加會得到雙份音訊。

import json
import requests

with requests.post(
    "https://api.hop-base.com/v1/t2a_v2",
    headers={"Authorization": "Bearer sk-your-key"},
    json={
        "model": "speech-2.8-turbo",
        "text": "這裡放一段較長的文案。",
        "stream": True,
        "stream_options": {"exclude_aggregated_audio": True},
        "voice_setting": {"voice_id": "Chinese (Mandarin)_News_Anchor"},
        "audio_setting": {"format": "mp3", "sample_rate": 32000},
    },
    stream=True,
    timeout=(10, 300),
) as resp, open("long.mp3", "wb") as out:
    resp.raise_for_status()
    for line in resp.iter_lines():
        if not line.startswith(b"data:"):
            continue
        event = json.loads(line[5:])
        data = event.get("data") or {}
        if data.get("audio"):
            out.write(bytes.fromhex(data["audio"]))
        if data.get("status") == 2:
            print(event["extra_info"]["usage_characters"])  # 計費字元數

請求參數

原生入口接受官方 T2A v2 請求體。下表的取值與預設值均為官方口徑;最後一列標出 HopBase 與官方不同、或僅做透傳的地方。

頂層欄位

voice_setting

audio_setting

文字內聯控制

• 停頓:<#x#>,x 為秒數,範圍 0.01-99.99,最多兩位小數(你好<#0.5#>世界)。只能放在兩段可朗讀文字之間,兩個標記連用會被拒絕。每個標記計 1 個計費字元。
• 內聯注音:緊跟在目標字詞後,用半形括號寫帶聲調 1-5 的拼音、IPA,或帶聲調 1-6 的粵拼:This is (he2)平, not (huo4)面.、pronounced (lɪv) as a verb、去街市買啲(sung3)。
• 語氣詞(僅 Speech 2.8):(laughs)、(chuckle)、(coughs)、(clear-throat)、(groans)、(breath)、(pant)、(inhale)、(exhale)、(gasps)、(sniffs)、(sighs)、(snorts)、(burps)、(lip-smacking)、(humming)、(hissing)、(emm)、(sneezes)。

系統音色

voice_id 一列請原樣使用——大小寫、空格、括號都不能改。「名稱」是官方標籤。

粵語音色需要 language_boost: "Chinese,Yue"。上表只是起步範例:MiniMax 官方系統音色列表裡的音色(24 種語言、332 個)全部可用,voice_id 照官方列表原樣傳即可。2026-09-16 逐個核驗:除 Cantonese_ProfessionalHost (F) 與 Cantonese_ProfessionalHost (M) 兩個官方列表有、服務端卻回傳 "voice id not exist" 之外,其餘全部可用。HopBase 目前不提供音色查詢介面。

效能與逾時

短文字(一兩句話)實測:同步入口約 1.5-2.4 秒回傳整段音訊;stream: true 時首個音訊塊約 1 秒到達。延遲隨文字長度增長,長文字請走串流(MiniMax 建議超過 3000 字元即串流),按上面的 SSE 範例邊收邊寫。同步請求的用戶端逾時沿用並行、逾時與計費裡其他同步介面的口徑:讀逾時不低於 300 秒。

計費

語音按計費字元數計費。權威值是原生回應裡的 extra_info.usage_characters;OpenAI 相容入口只回傳音訊,同一個數字請到控制台「使用記錄」看 tts_characters。每個 Unicode 字元計 1,漢字額外再計 1,即一個漢字按 2 計;標點、空格、emoji 與 <#0.5#> 這類停頓標記各計 1。

• Hello, world. → 13 個計費字元
• 你好,世界 → 5 個字元,其中 4 個漢字 → 9 個計費字元

被 400 拒絕或合成過程中失敗的請求不計費,串流沒有收到末塊也不計費。官方牌價(每百萬字元)見價格頁,你所在分組的實際單價以登入後的模型廣場為準。

錯誤與建議

所有 400 的回應體都是 {"error":{"message":…,"type":"invalid_request_error","code":…}},message 會指出出錯的欄位。

• 中文文字請選普通話音色。
• 長文字自行分段:OpenAI 相容入口每次 4096 字元,原生入口 10000 字元。
• 用 opus 時務必帶上 sample_rate。

與 OpenAI 官方 TTS 的差異:沒有 tts-1 這個模型名(用上面兩個 ID)、不支援 stream_format、instructions 無效、voice 取值是 MiniMax 音色 ID。