跳到主要内容

Matrix TTS API

matrix-tts-v1 是 Matrix 的自研语音合成模型，输出 48 kHz 单声道音频。 支持零样本声音克隆与按属性设计音色，服务端支持动态合批，是批量场景下吞吐最高的语音模型。

支持多语种，服务端会根据文本自动识别语种，一般无需额外声明。

快速开始​

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/audio/speech' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "matrix-tts-v1",
    "input": "你好，这是一段由 Matrix TTS 生成的语音。"
  }' \
  --output speech.wav

请求参数​

参数类型必填说明
modelstring是固定为 matrix-tts-v1
inputstring是待合成文本，上限 4000 字符
instructionsstring否音色属性描述，取值必须来自下方词典
ref_audiostring否Base64 编码的参考音频，用于声音克隆
ref_textstring否参考音频对应的文字
speednumber否语速
response_formatstring否wav（默认）、flac、ogg、opus

:::note 关于 voice 参数

matrix-tts-v1 没有预置音色，voice 字段对本模型不生效，传入任意名称都不会改变音色。 需要指定音色请使用 ref_audio 克隆，或用 instructions 描述音色属性。

需要按名称选择现成音色时，请改用 index-tts-v2。

:::

三种合成方式​

合成方式由传入的参数自动决定，无需显式声明：

方式传入参数效果
默认音色仅 input使用模型默认发音
音色设计input + instructions按性别、年龄、音调等属性生成音色
声音克隆input + ref_audio复刻参考音频中的音色

声音克隆​

参考音频以 Base64 放入 JSON 请求体：

REF_B64=$(base64 -i my-voice.wav | tr -d '\n')

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/audio/speech' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"matrix-tts-v1\",
    \"input\": \"用我的声音念这句话。\",
    \"ref_audio\": \"${REF_B64}\",
    \"ref_text\": \"参考音频里说的那句话\"
  }" \
  --output cloned.wav

ref_text 可选。提供准确的参考文字可以提升音色相似度；不提供时服务端会自动识别参考音频内容， 首次合成耗时略长。

同一段参考音频在后续请求中会被服务端复用，重复使用同一音色时合成更快。

音色设计​

instructions 只接受下列固定词条，不支持自由描述（例如「温柔一点」会返回 400）：

类别可选值
性别男 / male，女 / female
年龄儿童 / child，少年 / teenager，青年 / young adult，中年 / middle-aged，老年 / elderly
音调极低音调 / very low pitch，低音调 / low pitch，中音调 / moderate pitch，高音调 / high pitch，极高音调 / very high pitch
耳语耳语 / whisper
口音（仅英文）american accent、british accent、australian accent、canadian accent、indian accent、chinese accent、japanese accent、korean accent、portuguese accent、russian accent
方言（仅中文）河南话、陕西话、四川话、贵州话、云南话、桂林话、济南话、石家庄话、甘肃话、宁夏话、青岛话、东北话

同一类别内的词条互斥，只能选一个。中文词条之间用全角逗号 ， 分隔，英文词条之间用半角逗号加空格 , 分隔，不要混用中英文。

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/audio/speech' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "matrix-tts-v1",
    "input": "欢迎收听今天的节目。",
    "instructions": "女，青年，高音调"
  }' \
  --output designed.wav

传入不支持的词条时，400 响应的 message 中会列出全部合法词条，可据此排查。

输出​

返回 48 kHz、单声道、16 位音频。默认为 WAV。

请求 mp3 或 pcm 不会报错，但返回的仍是 WAV 数据，详见语音合成总览。

错误码​

状态码触发条件
400input 为空或超过 4000 字符；ref_audio 不是合法 Base64；instructions 含不支持的词条；response_format 不支持
503模型加载中或服务繁忙
504合成超时

其余错误码见语音合成总览。