本文详细介绍语音合成模型 IndexTeam/IndexTTS-2 的 API 调用方法，包括两类核心接口的输入输出参数、请求示例、响应格式、注意事项及常见问题，供接口调用时查阅字段含义及使用规范。

1. 认证方式

所有接口均采用 API Key 认证，需在请求头中携带 Authorization 字段，格式如下：

Authorization: Bearer $MODELVERSE_API_KEY

说明：将 $MODELVERSE\_API\_KEY 替换为您实际的 API Key，即可完成身份认证，获取接口调用权限。

2. 核心接口一：/v1/audio/infer

该接口用于通过参考音频提取音色、情感特征，结合配置参数完成语音合成，请求体格式必须为 multipart/form\-data（表单模式）。

2.1 接口地址

https://api.modelverse.cn/v1/audio/infer

2.2 请求参数（Form Data 表单文件参数）

2.3 payload 配置参数（JSON 格式）

2.4 请求示例（curl）

如果您使用 Windows 系统，建议使用 Postman 或其他 API 调用工具，避免命令行调用出现兼容问题。

curl https://api.modelverse.cn/v1/audio/infer \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "model=IndexTeam/IndexTTS-2" \
  -F "spk_audio_file=@audio/klee.wav" \
  -F "emo_audio_file=@audio/emo_sad.wav" \
  -F "payload={
    \"input\": \"酒楼丧尽天良，开始借机竞拍房间，哎，一群蠢货。\",
    \"emo_weight\": 0.8,
    \"emo_control_method\": 1
  }" \
  --output 007_sad_08.wav

2.5 响应格式

API 返回二进制音频文件流，具体说明如下：

• 音频格式：目前仅支持 WAV 格式输出

• Content-Type：audio/wav

2.6 错误响应

当请求失败时，API 会返回标准的 JSON 格式错误响应：

{
  "error": {
    "message": "错误描述信息",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "<请求 ID，用于反馈或排查错误原因>"
  }
}

3. 核心接口二：/v1/audio/speech（兼容接口）

该接口为兼容接口，支持通过内置音色或自定义音色完成语音合成，请求体格式为 JSON。

3.1 接口地址

https://api.modelverse.cn/v1/audio/speech

3.2 请求参数（JSON 格式）

3.3 调用示例

以下示例展示如何使用 IndexTeam/IndexTTS-2 模型进行语音合成，请确保将 $MODELVERSE_API_KEY 替换为您自己的 API Key。

3.3.1 curl 示例（使用内置音色）

curl https://api.modelverse.cn/v1/audio/speech \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $MODELVERSE_API_KEY" \
 -d '{
   "model": "IndexTeam/IndexTTS-2",
   "input": "你好！欢迎使用 Modelverse 语音合成服务。",
   "voice": "jack_cheng"
 }' \
 --output speech.wav

4. 使用自定义音色（可选）

除使用内置音色外，您可上传自己的音色（含特定情绪的样例语音），生成专属 voice_id，在 TTS 请求中通过 voice 字段引用。

注意：当前自定义音色资源会在上传 7 天后自动清理，如需长期使用请注意提前备份或重新上传；可联系商务团队咨询长期保存需求。

4.1 自定义音色使用步骤

1. 上传音色，获取 voice_id：调用 POST /v1/audio/voice/upload 上传符合要求的示例语音，接口会返回一个 id 作为自定义音色 ID；详细请求参数与返回结构请参考《自定义音色管理 API 文档》。

2. 在 TTS 请求中使用 voice_id：在 /v1/audio/speech 请求中，将 voice 字段设置为步骤一返回的 id 即可（示例见 4.2）。

3. 管理已有的自定义音色（可选）：如需查看或删除已有音色，可调用 GET /v1/audio/voice/list 和 POST /v1/audio/voice/delete；具体请求/返回格式见《自定义音色管理 API 文档》。

提示：自定义音色完全兼容 OpenAI 协议，仅复用 voice 字段，无需学习新的参数名。

4.2 自定义 voice_id 调用示例（curl）

VOICE_ID="uspeech:xxxx-xxxx-xxxx-xxxx"

curl https://api.modelverse.cn/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -d "{
    \"model\": \"IndexTeam/IndexTTS-2\",
    \"input\": \"你好，我是自定义的温柔女声。\",
    \"voice\": \"$VOICE_ID\"
  }" \
  --output speech-custom.wav

4.3 voice 字段行为说明

• voice 为空：使用默认音色或模型自带的默认配置。

• voice 为内置名称（如 jack_cheng 等）：使用平台内置的预置音色。

• voice 为形如 uspeech:xxxx 的值：使用您上传的自定义音色，平台会根据该 ID 查找并应用对应的音色/情绪素材，无需额外配置。

4.4 响应格式

与 /v1/audio/infer 接口一致，API 返回二进制音频文件流：

• 音频格式：目前仅支持 WAV 格式输出

• Content-Type：audio/wav

4.5 错误处理

当请求失败时，API 会返回标准的 JSON 格式错误响应，与 /v1/audio/infer 接口错误响应格式一致：

{
  "error": {
    "message": "错误描述信息",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "<请求 ID，用于反馈或排查错误原因>"
  }
}

5. 注意事项

• 音频格式：所有接口响应的二进制流格式目前仅支持 WAV，暂不支持其他音频格式。

• 文本长度限制：单次请求的文本长度限制为 600 字符以内（IndexTeam/IndexTTS-2 模型）。

• 语音类型：不同的 voice 参数会产生不同音色和风格的语音效果，建议根据实际场景选择合适的语音类型。

• 参考音频要求：spk_audio_file 和 emo_audio_file 仅支持 MP3、WAV 格式，单个文件 ≤ 20MB，时长 5–30 秒，采样率至少 16kHz，不符合要求会返回 4xx 错误。

6. 常见问题（FAQ）

Q：我上传的音频有什么要求？

A：必须是 MP3/WAV 格式，单个文件 ≤ 20MB，时长 5–30 秒，采样率至少 16kHz，不符合要求会返回 4xx 错误，并在 error.code 中标明原因。

Q：voice 字段应该填什么？

A： 1. 想直接用平台提供的固定音色：填写内置名称（如 jack_cheng）； 2. 想用自己录制的音色：先调用上传接口拿到 id，然后在 TTS 请求中把 voice 设置为这个 id（例如 uspeech:xxxx）。

Q：出现 invalid_voice_id / voice_not_found 等错误怎么办？

A：说明当前账号下找不到这个 voice_id，或者已被删除。可以先调用 /v1/audio/voice/list 确认当前可用的 ID，再在请求里使用正确的值。

Q：不同账号之间能共享自定义音色吗？

A：同一组织下所有子账号，自定义音色可以共享。非同一账号下，无法共享。