自定义音色管理 API 文档

本文仅描述自定义音色相关管理接口（上传 / 列表 / 删除）的 请求与响应格式，适合已有开发基础的用户参考。如何在 /v1/audio/speech 中实际使用自定义音色，请查看《OpenAI TTS API 调用文档》中的「使用自定义音色（可选）」一节。

概述

• 域名示例：https://api.modelverse.cn
• 认证方式：所有接口都需要在 Header 中携带 Authorization: Bearer <MODELVERSE_API_KEY>。
• 组织隔离：
  • 自定义音色按组织维度隔离；同一组织下所有子账号可以共享该组织内的自定义音色；
  • 不同组织之间无法共享。
• 生命周期：自定义音色默认保存 7 天，超期会被后台任务清理；如有长期保存需求，可联系商务团队评估方案。

---

1. 上传自定义音色

• HTTP 方法：POST
• 路径：/v1/audio/voice/upload
• Content-Type：
  • 推荐：multipart/form-data（直接上传文件）
  • 也支持：表单字段传 Base64 字符串或远程 URL

1.1 请求参数

公共字段

字段	类型	必填	说明
name	string	是	音色名称，用于列表展示，例如「温柔女声」「客服音色A」。
model	string	是	使用该音色时对应的 TTS 模型名称，例如 IndexTeam/IndexTTS-2。与后续 /v1/audio/speech 请求中的 model 保持一致。

Speaker（音色语料音频，三选一，必填其一）

字段	类型	必填	说明
speaker_file	file	是（三选一必填）	本地音频文件（推荐方式），通过 multipart/form-data 上传。
speaker_file_base64	string	是（三选一必填）	speaker_file 的 Base64 字符串，通过普通表单字段传递。
speaker_url	string	是（三选一必填）	可访问的公网 URL，指向音色音频文件。

说明：

• speaker_* 三个字段 三选一，至少提供其一；
• 若同时提供多个，优先级为：speaker_file → speaker_file_base64 → speaker_url；
• 若三者均未提供，请求会被拒绝（错误码：missing_speaker）。

Emotion（情绪样例音频，三选一，可选）

字段	类型	必填	说明
emotion_file	file	否（三选一可选）	情绪样例音频文件，通过 multipart/form-data 上传。
emotion_file_base64	string	否（三选一可选）	emotion_file 的 Base64 字符串，通过普通表单字段传递。
emotion_url	string	否（三选一可选）	可访问的公网 URL，指向情绪样例音频文件。

说明：

• emotion_* 字段整体可选，可不提供；
• 若同时提供多个，优先级为：emotion_file → emotion_file_base64 → emotion_url；
• 若完全不传 emotion_*，则只基于 Speaker 构建音色特征。

1.2 音频文件约束

对 speaker_* 与 emotion_* 上传的音频均适用以下约束：

• 格式：仅支持 MP3、WAV
• 大小：单个音频 ≤ 20MB
• 时长：5–30 秒
• 采样率：16kHz 及以上

若不满足上述任一条件，接口会返回 4xx 错误，并在 error.code 中标明具体原因（如 file_too_large、duration_out_of_range、sample_rate_too_low 等）。

1.3 请求示例（推荐：multipart 文件上传）

curl -X POST "https://api.modelverse.cn/v1/audio/voice/upload" \
 -H "Authorization: Bearer $MODELVERSE_API_KEY" \
 -H "Content-Type: multipart/form-data" \
 -F "name=温柔女声" \
 -F "model=IndexTeam/IndexTTS-2" \
 -F "speaker_file=@/path/to/speaker.wav" \
 -F "emotion_file=@/path/to/emotion.wav"

1.4 成功响应示例

{
 "id": "uspeech:xxxx-xxxx-xxxx-xxxx"
}

• id：自定义音色 ID，后续在 /v1/audio/speech 请求中通过 voice 字段引用（例如："voice": "uspeech:xxxx-xxxx-xxxx-xxxx"）。

1.5 失败响应示例

所有错误响应都会采用统一格式：

{
 "error": {
 "message": "错误描述信息",
 "type": "invalid_request_error",
 "code": "missing_speaker",
 "param": "<请求 ID 或参数名>"
 }
}

常见错误码示例：

• missing_name：未提供 name 字段；
• missing_speaker：未提供任意一个 speaker_* 字段；
• invalid_speaker_base64：speaker_file_base64 解码失败；
• unsupported_audio_format：音频格式不是 MP3/WAV；
• file_too_large / duration_out_of_range / sample_rate_too_low：音频不符合大小、时长或采样率限制。

---

2. 查询自定义音色列表

• HTTP 方法：GET
• 路径：/v1/audio/voice/list

2.1 请求说明

• 无请求体，仅需在 Header 中携带鉴权信息。
• 系统会根据当前 API Key 所属组织（top_org_id）返回该组织下的自定义音色列表。
• 为保证接口性能，单次调用最多返回 1000 条记录。

2.2 响应示例

{
 "list": [
 { "id": "uspeech:xxxx", "name": "温柔女声" },
 { "id": "uspeech:yyyy", "name": "沉稳男声" }
 ]
}

字段说明：

字段	类型	说明
list	array	自定义音色列表。
list[].id	string	自定义音色 ID，可在 /v1/audio/speech 的 voice 字段中引用。
list[].name	string	创建时填写的音色名称，仅用于展示。

---

3. 删除自定义音色

• HTTP 方法：POST
• 路径：/v1/audio/voice/delete
• Content-Type：application/json

3.1 请求参数

字段	类型	必填	说明
id	string	是	要删除的自定义音色 ID，即上传接口返回的 id。

3.2 请求示例

curl -X POST "https://api.modelverse.cn/v1/audio/voice/delete" \
 -H "Authorization: Bearer $MODELVERSE_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "id": "uspeech:xxxx"
 }'

3.3 成功响应示例

{
 "success": true
}

说明：删除成功后，该 voice_id 将无法继续在 /v1/audio/speech 请求中使用，请在确认业务不再引用后再删除。

3.4 可能的错误码

• missing_id：请求体中未提供 id 字段；
• invalid_voice_id：指定的 id 在当前组织下不存在或已被删除；
• 其他 server_error：内部错误或对象存储异常，可结合返回的 message 与请求 ID 排查。

---

通过以上三个接口，可以完成自定义音色的完整生命周期管理：

1. 通过上传接口创建音色并获取 voice_id；
2. 在 TTS 调用中通过 voice 字段引用该 voice_id；
3. 通过列表/删除接口管理已有音色资源，并结合 7 天有效期策略控制存储成本。