语音合成 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。