语音合成

Mozia API 提供 OpenAI 兼容的语音合成接口。提交文本，同步返回音频文件，无需轮询任务状态。

接口

方法	路径	作用
`POST`	`/v1/audio/speech`	将文本合成为音频并直接返回

基础地址：https://mzsjai.com

所有请求都需要 API Key：

Authorization: Bearer <YOUR_API_KEY>

快速开始

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": "你好，这是一段由 Mozia API 生成的语音。"
  }' \
  --output speech.wav

响应体就是音频文件本身，Content-Type 随输出格式变化。请求失败时返回 JSON 错误对象。

选择模型

模型	采样率	音色来源	适合场景
`matrix-tts-v1`	48 kHz	参考音频克隆 / 属性描述	批量合成、长文本、多语种，吞吐最高
`voxcpm2`	48 kHz	参考音频克隆 / 自然语言描述	单条高保真，音色描述最自由
`index-tts-v2`	22.05 kHz	10 个预置音色 / 参考音频克隆	需要情感倾向控制的单条合成

批量或高并发场景请使用 matrix-tts-v1，它支持服务端动态合批。index-tts-v2 为串行处理，不适合承接批量流量。

实际可用模型以账号调用 GET /v1/models 返回的列表为准。单价见模型价格。

通用参数

三个模型共有的参数：

参数	类型	必填	说明
`model`	string	是	模型 ID
`input`	string	是	待合成文本
`response_format`	string	否	输出格式，默认 `wav`
`ref_audio`	string	否	Base64 编码的参考音频，用于声音克隆
`ref_text`	string	否	参考音频对应的文字，可提升克隆相似度

voice 和 instructions 在三个模型中含义不同，请参阅各模型文档。

文本长度

matrix-tts-v1 和 index-tts-v2 单次请求上限为 4000 字符，超出返回 400。长文本请在客户端按语义切分后分批合成，再拼接音频。

参考音频

ref_audio 使用 Base64 编码的音频内容，直接放在 JSON 请求体中，不是 multipart 文件上传，也不接受 URL：

REF_B64=$(base64 -i sample.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}\"
  }" \
  --output cloned.wav

matrix-tts-v1 与 index-tts-v2 也接受 data:audio/wav;base64,... 形式的 Data URL；voxcpm2 只接受纯 Base64 字符串。

建议使用 5～15 秒、单人、无背景噪音的清晰录音作为参考音频。

输出格式

`response_format`	`matrix-tts-v1`	`voxcpm2`	`index-tts-v2`
`wav`（默认）	✅	✅	✅
`flac`	✅	✅	✅
`ogg`	✅	✅	✅
`opus`	✅	❌ 返回 `422`	✅
`mp3` / `pcm`	⚠️ 实际返回 WAV	❌ 返回 `422`	⚠️ 实际返回 WAV

:::caution 请勿按扩展名假定文件格式

matrix-tts-v1 和 index-tts-v2 收到 mp3 或 pcm 时不会报错，但返回的仍是 WAV 数据。若直接存成 .mp3，文件内容与扩展名将不一致。需要 MP3 时请在客户端自行转码，或根据响应的 Content-Type 决定扩展名。

:::

计费

语音合成按 Token 计费，输入文本与输出音频分别计量：

输入 Token 由 input 文本长度决定。
输出 Token 由音频时长换算，约 每分钟音频 1000 Token。

单价见模型价格。计费口径可能调整，最终费用以账单记录为准。

错误处理

错误响应为 JSON：

{
  "error": {
    "message": "input must not be empty",
    "type": "invalid_request_error"
  }
}

状态码	说明	建议
`400`	文本为空或超长、参考音频不是合法 Base64、音色或属性描述不被支持	修正请求后重试
`401`	API Key 缺失或无效	检查鉴权配置
`422`	参数取值超出允许范围	按模型文档修正取值
`429`	额度不足或触发限流	检查余额并降低请求频率
`500`	合成失败	保存请求 ID 后联系平台
`503`	模型加载中或服务繁忙	稍后重试
`504`	合成超时	缩短文本后重试

接入建议

将 API Key 保存在服务端，不要写入浏览器代码、公开仓库或日志。
长文本先按句子或段落切分再分批合成，既能规避长度上限，也能降低单次失败的代价。
参考音频在多次请求中保持一致时，服务端可复用已解析的音色，合成更快。
对 503 和 504 使用指数退避进行有限重试；400 与 422 属于参数问题，重试不会成功。
响应可能包含 X-Matrix-* 或 X-Omnivoice-* 前缀的诊断头（生成耗时、音频时长等）。这些字段仅供排查参考，请勿作为业务依赖。

接口​

快速开始​

选择模型​

通用参数​

文本长度​

参考音频​

输出格式​

计费​

错误处理​

接入建议​

接口