VoxCPM2 API

voxcpm2 输出原生 48 kHz 单声道音频，音色可以用一句自然语言描述生成，也可以从参考音频克隆。 每个请求独立推理，适合对单条音质要求较高的场景；批量合成请使用 matrix-tts-v1。

快速开始

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

请求参数

参数	类型	必填	说明
model	string	是	固定为 voxcpm2
input	string	是	待合成文本
voice	string	否	自然语言音色描述，仅在不使用参考音频时生效
ref_audio	string	否	Base64 编码的参考音频，用于声音克隆
ref_text	string	否	参考音频对应的文字
response_format	string	否	仅支持 wav（默认）、flac、ogg

:::caution voice 的含义与其他模型不同

本模型的 voice 是一句自由描述（例如 "a calm young female voice"），不是音色名称。 传入 voice_01 这类音色 ID 不会报错，但会被当作描述文本处理，得不到预期音色。

index-tts-v2 的 voice 才是预置音色名，matrix-tts-v1 则不使用该字段。

:::

三种合成方式

方式	传入参数	效果
音色描述	input + voice	按自然语言描述生成音色
声音克隆	input + ref_audio	复刻参考音频的音色特征
高相似度克隆	input + ref_audio + ref_text	提供参考文字，音色还原度更高

音色描述

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": "voxcpm2",
    "input": "今天天气不错，适合出去走走。",
    "voice": "a calm young female voice, warm and slightly breathy"
  }' \
  --output designed.wav

描述可以用中文或英文，涵盖性别、年龄、语气、情绪、音色质感等。描述越具体，结果越稳定。

声音克隆

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\": \"voxcpm2\",
    \"input\": \"用这个音色念一句话。\",
    \"ref_audio\": \"${REF_B64}\",
    \"ref_text\": \"参考音频里说的那句话\"
  }" \
  --output cloned.wav

同时提供 ref_text 会启用高相似度克隆。ref_audio 只接受纯 Base64 字符串， 不支持 data:audio/... 形式的 Data URL。

使用参考音频时 voice 不生效。

输出

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

:::caution 输出格式限制更严格

本模型的 response_format 只接受 wav、flac、ogg。传入 mp3、pcm 或 opus 会直接返回 422， 而不像其他两个语音模型那样回退为 WAV。跨模型切换时请注意调整。

:::

性能特点

本模型逐条推理，不做合并批处理，单次合成耗时通常长于音频本身时长。 需要批量生成或对延迟敏感时，请改用支持动态合批的 matrix-tts-v1。

错误码

状态码	触发条件
400	input 为空；ref_audio 不是合法 Base64
422	response_format 不在 wav/flac/ogg 之内
503	模型加载中或服务繁忙

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