語音合成 API

本頁講兩家語音模型。MiniMax Speech 2.8 屬於獨立分組 MiniMax 語音 官方直連，下面各節預設講它；字節跳動豆包語音（seed-tts-2.0、seed-audio-1.0）屬於另一個分組，只走 OpenAI 相容入口，見豆包語音；同一分組的聲音複刻 seed-icl-2.0 見豆包聲音複刻。金鑰須包含對應分組才能調用；可以直接把分組加到已有的對話或影片金鑰上，不必另建。

合成語音

兩個入口都同步回傳整段音訊。想直接套用 OpenAI SDK，用 OpenAI 相容入口；需要完整參數與串流輸出，用原生入口。

MiniMax Speech 2.8 把文字同步合成為音訊，回應就是音訊本身，沒有任務要輪詢。它與其他模型共用同一個 Base URL(見頁首表格)和 Bearer 鑑權，沒有單獨的音訊網域或憑證。

模型 ID 區分大小寫、無別名，tts-1 / tts-1-hd 不會被識別。請使用已開通該分組的金鑰，並用 GET /v1/models 確認。

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 相容入口

POST /v1/audio/speech 接受 OpenAI 的請求結構，回應直接是音訊位元組。欄位說明也見 API 參考。

• 不傳 voice 時，文字含漢字用 Chinese (Mandarin)_News_Anchor，否則用 English_expressive_narrator。
• OpenAI 音色名同樣落到該預設音色。
• speed 在範圍內的值會被鉗到 0.5-2。
• 不支援 stream_format，傳了回傳 400。

用官方 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 請求體，閘道不認識的欄位也原樣透傳。JSON 回應同樣沿用官方結構（錯誤除外）。

data.audio 是十六進位編碼的音訊，extra_info 帶 usage_characters 與音訊中繼資料。傳 stream: true 切換為 SSE，寫法見邊合成邊接收。

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"])  # 計費字元數

閘道在原生入口只做三件事：

• 校驗 model、text 長度、stream 與 output_format。
• 把 voice_setting.speed 鉗到官方區間。
• 限制請求體 ≤1 MiB。

其餘欄位原樣透傳，超出官方範圍的值由服務回傳 400。下面各表的取值與預設值均為官方口徑。

(laughs) (chuckle) (coughs) (clear-throat) (groans) (breath) (pant) (inhale) (exhale) (gasps)
(sniffs) (sighs) (snorts) (burps) (lip-smacking) (humming) (hissing) (emm) (sneezes)

系統音色

MiniMax 官方系統音色列表裡的音色（24 種語言、332 個）全部可用，voice_id 照官方列表原樣傳即可。下表只是起步範例。

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

• 粵語音色需要 language_boost: "Chinese,Yue"。
• 中文文字請選普通話音色。
• 2026-09-16 逐個核驗，官方列表裡只有兩個音色不可用：服務端對它們回傳 "voice id not exist"。
• 這兩個是 Cantonese_ProfessionalHost (F) 與 Cantonese_ProfessionalHost (M)。
• 用 POST /v1/get_voice 傳 {"voice_type": "system"} 可以查詢系統音色列表。

邊合成邊接收

原生入口傳 stream: true 後切換為 SSE。每個 data: {...} 事件帶一段十六進位音訊，末塊 data.status 為 2 並附 extra_info。逐行讀回應體，把每個事件的音訊片段解碼後追加寫入檔案。

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:])
        base = event.get("base_resp") or {}
        if base.get("status_code", 0) != 0:  # 中途失敗:不計費,串流隨即結束
            raise RuntimeError(base.get("status_msg"))
        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"])  # 計費字元數

延遲與逾時

短文字（一兩句話）實測：同步入口約 1.5-2.4 秒回傳整段音訊；stream: true 時首個音訊塊約 1 秒到達。

延遲隨文字長度增長，長文字請走串流（MiniMax 建議超過 3000 字元即串流）。同步請求的用戶端逾時沿用並行、逾時與計費裡其他同步介面的口徑：讀逾時不低於 300 秒。

聲音複製

用你自己的錄音複製出音色，之後在兩個入口裡像系統音色一樣使用。流程與 MiniMax 官方聲音複製 API 一致，官方 SDK 程式碼改 Base URL 與金鑰即可沿用。金鑰所屬分組須包含 MiniMax 語音模型。

1. 上傳音訊

POST /v1/files/upload 以 multipart/form-data 提交，只接受下面兩個欄位，其他欄位回傳 400。

• voice_clone 是要複製的錄音，prompt_audio 是選填的範例片段。
• 時長：voice_clone 10 秒至 5 分鐘，prompt_audio 短於 8 秒。
• 時長在複製時校驗。

curl https://api.hop-base.com/v1/files/upload \
  -H "Authorization: Bearer sk-your-key" \
  -F purpose=voice_clone \
  -F file=@my_voice.mp3
# → {"file":{"file_id":123456789,"bytes":…,"created_at":…,"filename":"my_voice.mp3","purpose":"voice_clone"},"base_resp":{…}}

2. 複製音色

POST /v1/voice_clone 傳入 file_id 與你自己起的 voice_id。帶上 text 與 model 可拿到試聽音訊。

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyNarrator01",
    "text": "Hello, this is my cloned voice.",
    "model": "speech-2.8-hd",
    "need_noise_reduction": true
  }'
# 回應:input_sensitive、input_sensitive_type、demo_audio(api.hop-base.com 上的試聽下載連結,24 小時內有效;不傳 text 時為空)、extra_info.usage_characters(試聽計費字元數)、base_resp

• voice_id 由字母、數字、-、_ 組成，以字母開頭，不以 - 或 _ 結尾。
• clone_prompt 寫作 {"prompt_audio": <file_id>, "prompt_text": "…"}，兩個鍵都必填。
• prompt_text 是範例片段的逐字文字，以標點結尾。

使用複製音色

把你的 voice_id 填到 /v1/audio/speech 的 voice，或 /v1/t2a_v2 的 voice_setting.voice_id（以及 timber_weights[].voice_id）。

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": "Hello again.", "voice": "MyNarrator01"}' \
  --output cloned.mp3

• 上傳的檔案只能用一次：複製成功後來源音訊與範例音訊都會自動刪除，再次複製須重新上傳。
• 複製失敗則保留檔案，可換參數重試。
• 上傳後 24 小時內未使用的檔案自動刪除。刪除檔案不影響已複製的音色。
• 複製後 7 天內未用於合成的音色自動刪除，且不收複製費。
• 音色只屬於你的帳戶（企業帳戶下由企業主名下成員的金鑰共享）；其他帳戶即使知道 voice_id 也用不了。

# 列出複製音色("system" 為系統音色,"all" 為全部;"voice_generation" 始終為空)
curl https://api.hop-base.com/v1/get_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"voice_type": "voice_cloning"}'
# 刪除複製音色
curl https://api.hop-base.com/v1/delete_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"voice_type": "voice_cloning", "voice_id": "MyNarrator01"}'
# 尚未使用的上傳檔案:列表、查詢、刪除
curl "https://api.hop-base.com/v1/files/list?purpose=voice_clone" -H "Authorization: Bearer sk-your-key"
curl "https://api.hop-base.com/v1/files/retrieve?file_id=123456789" -H "Authorization: Bearer sk-your-key"
curl https://api.hop-base.com/v1/files/delete \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"file_id": 123456789, "purpose": "voice_clone"}'

計費

語音按計費字元數計費。權威值是原生回應裡的 extra_info.usage_characters；OpenAI 相容入口只回傳音訊，同一個數字請到控制台「使用記錄」看 tts_characters。

每個 Unicode 字元計 1，漢字額外再計 1，即一個漢字按 2 計。標點、空格、emoji 與 <#0.5#> 這類停頓標記各計 1。

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

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

上傳與複製免費。複製費只收一次，在音色首次合成成功時一併扣除，那次合成的使用記錄明細裡多一項 voice_clone_activation。

試聽 text 只按語音字元計費，不算首次使用；失敗的請求不計費。複製費見價格頁。

錯誤與建議

兩個入口的錯誤都是非 200 狀態碼加 {"error":{…}}，不是官方的 base_resp。閘道自身校驗（模型、文字、格式、語速、未知欄位）不帶 code，以 message 為準。

聲音複製的 400 包括：file_id 已用過或已過期、voice_id 已被占用、音訊時長超出範圍，或 text_validation 比對未通過。常見報文與改法：

400 voice id not exist                       音色 ID 不存在,或複製音色已刪除 / 過期
400 file_id ... does not exist; uploaded files are single-use and expire 24 hours after upload    重新上傳
400 voice_id ... already exists             換名字或刪除舊音色
400 (複製)音訊時長超出範圍                   來源音訊 10 秒-5 分鐘,範例音訊短於 8 秒
400 (複製)語音辨識比對未通過                 僅傳 text_validation 時出現:修正預期文字或調低 accuracy
503 voice cloning is temporarily unavailable    稍後重試
400 sensitive content / >10% invalid chars   改寫或清理文字
400 invalid request parameters; check text, voice_setting and audio_setting (opus requires an explicit sample_rate)
413 request body exceeds the 1048576 byte limit (got N bytes)            請求體超過 1 MiB
502 response_size_limit_exceeded (audio over 64 MiB)    改用 stream: true、縮短文字或降低位元率
串流中途失敗:最後推一條 data: {"base_resp":{...}} 後斷流,不計費

豆包語音

字節跳動豆包語音的兩個模型屬於獨立分組 豆包語音 雲廠商，金鑰須包含這個分組才能調用；可以直接把它加到已有的金鑰上。它們只走 OpenAI 相容入口 POST /v1/audio/speech，同步回傳整段音訊，不支援串流；原生入口 /v1/t2a_v2 不支援這兩個模型，呼叫會回傳 400 並提示改用 /v1/audio/speech。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-tts-2.0",
    "input": "你好，歡迎使用豆包語音合成。",
    "voice": "zh_female_vv_uranus_bigtts"
  }' \
  -o out.mp3

用官方 openai SDK 時，只需改 Base URL 與 model / voice 取值。seed-audio-1.0 的 input 寫場景與台詞：

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="seed-tts-2.0",
    voice="zh_female_vv_uranus_bigtts",
    input="你好，歡迎使用豆包語音合成。",
)
response.write_to_file("out.mp3")

# 場景音訊:input 寫「場景描述 + 台詞」,生成約需 10-30 秒
scene = client.audio.speech.create(
    model="seed-audio-1.0",
    voice="alloy",  # SDK 要求傳 voice;OpenAI 音色名等同不指定,聲音由描述決定
    input="先是一声手机震动的声音，随后一名男子（中青年，嗓音低沉）用严肃语气说道：“钟sir，你是什么时候被收买的？”",
    timeout=300,
)
scene.write_to_file("scene.mp3")

豆包語音參數

• seed-tts-2.0：不傳 voice，或傳 alloy 等 OpenAI 標準音色名時，依文字語言自動選預設音色：中文用 zh_female_vv_uranus_bigtts，其他語言用 en_female_dacey_uranus_bigtts。可指定其他 2.0 音色（ID 以 _uranus_bigtts 結尾，如 zh_male_m191_uranus_bigtts）。
• seed-audio-1.0：input 寫「場景描述 + 台詞」，如上方範例。不傳 voice 或傳 OpenAI 標準音色名時，聲音由描述決定；也可以指定豆包音色 ID。描述過長時，要生成的音訊可能超出模型的時長上限，回傳 400 duration_out_of_range，縮短後再發。
• 輸出：seed-tts-2.0 為 24 kHz 單聲道（pcm 為 24 kHz、16 位元單聲道原始資料，與 OpenAI 一致）；seed-audio-1.0 為 48 kHz 雙聲道。
• 不支援串流，傳 stream_format 回傳 400。音色與文字語言不相符（如英文音色唸純中文）而沒有生成任何音訊時，回傳 400 no_audio。
• 更長的文字請在客戶端按上限分段，逐段請求後拼接。

耗時與計費

• seed-tts-2.0：短句約 1-3 秒，2000 字約 70 秒。
• seed-audio-1.0：約 10-30 秒。
• 兩者都要等整段音訊生成完才回傳。客戶端讀取逾時沿用並行、逾時與計費裡同步介面的口徑：不低於 300 秒。
• seed-tts-2.0 按輸入字元數計費，seed-audio-1.0 按生成音訊的時長計費，官方價見上方型號表；你所在分組的實際單價以登入後的模型廣場為準。被 400 拒絕或生成失敗的請求不計費。

上表各項不符合時回傳 400，請依報錯修正後再發，不要原樣重試；用 /v1/t2a_v2 呼叫也回傳 400。402、404、429、503 的含義與處理同上方錯誤與建議。

豆包聲音複刻

用一段你自己的錄音複刻出專屬音色，再用它合成語音。模型是 seed-icl-2.0（豆包聲音複刻 2.0），與豆包語音同在「豆包語音 雲廠商」分組，金鑰須包含這個分組才能調用。流程分三步：POST /v1/voice_clone 上傳錄音拿到 voice_id（hbv_ 開頭），再把它填進 POST /v1/audio/speech 的 voice 合成；不用時可查詢或刪除。

請求格式與上方 MiniMax 聲音複製不同：錄音直接以 base64 放在 JSON 裡，不用先上傳檔案；三個複刻介面的請求主體都必須帶 "model": "seed-icl-2.0"。同時使用 MiniMax 聲音複製與豆包聲音複刻時，建議兩者各用一把金鑰。

測試期名額：測試期每個帳戶最多保留 1 個複刻音色。想換聲音，先刪除舊音色再複刻，或帶上原 voice_id 重新訓練。複刻音色名額有限，額滿時回傳 503 voice_capacity_full，稍後再試即可。

1. 複刻音色

POST /v1/voice_clone，請求主體為 JSON，上限 16 MiB。

• language 可選值：zh、en、ja、es、id、pt、de、fr、ko、it、th、vi、ru、fil、ms、ar、es-mx、pt-br、pl、tr、sv。
• 複刻同步完成：實測 17 秒的錄音約 33 秒回傳。用戶端讀取逾時請設為不低於 300 秒。

# 把錄音轉成 base64 寫進請求主體(jq 1.6+)
jq -n --rawfile audio <(base64 < my_voice.wav | tr -d '\n') \
  '{model: "seed-icl-2.0", audio: $audio, language: "zh", demo_text: "你好，這是我複刻出來的聲音。"}' > clone.json

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d @clone.json

{
  "voice_id": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4",
  "status": "ready",
  "language": "zh",
  "remaining_trainings": 14,
  "created_at": 1792051200,
  "demo_audio": "<base64 音訊>",
  "demo_audio_format": "wav"
}

2. 用複刻音色合成

POST /v1/audio/speech，model 填 seed-icl-2.0，voice 填複刻得到的 voice_id。其餘參數、可選格式與上限與 seed-tts-2.0 相同（見豆包語音參數）：input 不超過 5000 字元，response_format 可選 mp3 / opus / aac / wav / pcm，speed 為 0.5-2.0，輸出 24 kHz 單聲道，同步回傳整段音訊，不支援串流。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0", "input": "今天的會議改到下午三點。", "voice": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4"}' \
  -o cloned.mp3

• seed-icl-2.0 只能用你自己複刻的音色：不傳 voice、傳系統音色或 OpenAI 音色名，回傳 400 voice_required。
• 複刻音色只能配 seed-icl-2.0，配其他模型回傳 400 unknown_voice。
• 複刻音色只屬於你的帳戶（企業帳戶下由企業主名下成員的金鑰共享）；其他帳戶即使知道 voice_id 也用不了。

3. 查詢與刪除

兩個介面都免費，請求主體同樣要帶 model。

# 列出你的複刻音色(帶 voice_id 則只查這一個)
curl https://api.hop-base.com/v1/get_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0"}'
# → {"voices":[{"voice_id":"hbv_k3m9x2p7q8r4t6w1y5z0a2b4","status":"ready","language":"zh","remaining_trainings":14,"created_at":1792051200}]}

# 刪除複刻音色
curl https://api.hop-base.com/v1/delete_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0", "voice_id": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4"}'
# → {"voice_id":"hbv_k3m9x2p7q8r4t6w1y5z0a2b4","deleted":true}

帶 voice_id 查詢時直接回傳該音色的物件（欄位同複刻回應，不含試聽音訊）。刪除後這個 voice_id 不能再用，名額隨即釋放。

聲音複刻計費

• 用複刻音色合成：按輸入字元數計費，官方價 ¥3 / 萬字元，與 seed-tts-2.0 相同。
• 試聽：demo_text 按同一價格計字元。
• 複刻本身、查詢、刪除都不收費，目前不收複刻費。失敗的請求不計費。

你所在分組的實際單價以登入後的模型廣場為準。

聲音複刻報錯

錯誤格式與其他介面相同：非 200 狀態碼加 {"error":{"message","type","code"}}。參數校驗類錯誤不帶 code，以 message 為準。

下一步

• 可用模型——所有模型 ID 及其分組
• 建立語音 API 參考
• MiniMax 海螺 H3 影片 API
• 錯誤碼與重試
• 並行、逾時與計費