可自定义音色管理 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 排查。

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

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

IndexTeam/IndexTTS 扩展参数价格说明