自定义音色管理

本文仅描述自定义音色相关管理接口（上传 / 列表 / 删除）的请求与响应格式，适用于已有开发基础的用户。若需了解如何在 /v1/audio/speech 中实际使用自定义音色，请查看《OpenAI TTS API 调用文档》\\「使用自定义音色（可选）」\\ 一节，链接：https://docs.ucloud.cn/modelverse/api_doc/audio_api/ttts。

概述

基础信息

域名示例：https://api.modelverse.cn
认证方式：所有接口均需在 HTTP Header 中携带 Authorization: Bearer \<MODELVERSE\_API\_KEY\>，替换为实际 API Key 完成鉴权。

核心规则

组织隔离：自定义音色按组织维度隔离；同一组织下所有子账号可共享该组织内的自定义音色；不同组织之间无法共享。
生命周期：自定义音色默认保存 7 天，超期将被后台任务自动清理；如有长期保存需求，可联系商务团队评估专属方案。

1. 上传自定义音色

该接口用于上传专属音色音频（含音色语料、可选情绪样例），并获取可在 TTS 接口中引用的自定义音色 ID。

1.1 接口基础信息

HTTP 方法：POST
请求路径：/v1/audio/voice/upload
Content-Type 支持：
- 推荐：multipart/form\-data（直接上传本地音频文件）
- 兼容：表单字段传 Base64 字符串、公网 URL 地址

1.2 请求参数

请求参数分为公共字段、Speaker（音色语料音频，三选一必填）、\\Emotion（情绪样例音频，三选一可选）\\ 三类，具体如下：

1.2.1 公共字段

字段	类型	必填	说明
name	string	是	音色名称，用于列表展示（如「温柔女声」「客服音色 A」）
model	string	是	绑定的 TTS 模型名称，需与后续 `/v1/audio/speech` 请求中的 `model` 保持一致（固定填：IndexTeam/IndexTTS-2）

1.2.2 Speaker 字段（三选一必填）

音色语料音频为创建音色的核心，需从以下三个字段中至少选择一个提供；若同时提供多个，优先级为：speaker\_file > speaker\_file\_base64 > speaker\_url。

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

1.2.3 Emotion 字段（三选一可选）

情绪样例音频为可选配置，用于丰富音色的情感表现；若同时提供多个，优先级为：emotion\_file > emotion\_file\_base64 > emotion\_url；若不提供，仅基于音色语料构建基础音色。

字段	类型	必填	说明
emotion_file	file	否（三选一）	本地情绪样例音频文件，通过 `multipart/form\-data` 直接上传
emotion_file_base64	string	否（三选一）	情绪样例音频的 Base64 编码字符串
emotion_url	string	否（三选一）	可公网访问的情绪样例音频 URL 地址

1.3 音频文件约束

speaker\_\* 与 emotion\_\* 上传的音频均需满足以下约束，否则接口返回 4xx 错误，并在 error\.code 中标注原因：

约束项	要求
格式	仅支持 MP3、WAV 格式
大小	单个音频文件 ≤ 20MB
时长	5–30 秒
采样率	≥ 16kHz

1.4 请求示例（推荐：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/your/speaker.wav" \
  -F "emotion_file=@/path/to/your/emotion.wav"

1.5 响应格式

1.5.1 成功响应示例

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

字段说明：id 为自定义音色 ID，后续在 /v1/audio/speech 接口中通过 voice 字段引用（如 \&\#34;voice\&\#34;: \&\#34;uspeech:xxxx\-xxxx\-xxxx\-xxxx\&\#34;）。

1.5.2 失败响应示例

所有接口均采用统一 JSON 错误响应格式：

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

1.5.3 常见错误码

错误码	说明
missing_name	未提供 `name` 字段
missing_speaker	未提供任意一个 `speaker\_\*` 字段
invalid_speaker_base64	`speaker\_file\_base64` 解码失败
unsupported_audio_format	音频格式非 MP3/WAV
file_too_large	音频文件超过 20MB
duration_out_of_range	音频时长不在 5–30 秒范围内
sample_rate_too_low	音频采样率低于 16kHz

2. 查询自定义音色列表

该接口用于查询当前组织下已上传的所有自定义音色信息。

2.1 接口基础信息

HTTP 方法：GET
请求路径：/v1/audio/voice/list
请求体：无（仅需携带鉴权 Header）
返回限制：单次调用最多返回 1000 条记录，保证接口性能。

2.2 请求示例

curl -X GET "https://api.modelverse.cn/v1/audio/voice/list" \
  -H "Authorization: Bearer <MODELVERSE_API_KEY>"

2.3 响应示例

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

2.4 字段说明

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

3. 删除自定义音色

该接口用于删除当前组织下的自定义音色，释放资源并避免无效引用。

3.1 接口基础信息

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

3.2 请求参数

字段	类型	必填	说明
id	string	是	要删除的自定义音色 ID（上传接口返回的 `id`，格式为 `uspeech:xxxx\-xxxx\-xxxx\-xxxx`）

3.3 请求示例

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-xxxx-xxxx-xxxx"
  }'

3.4 响应格式

3.4.1 成功响应示例

{
  "success": true
}

说明：删除成功后，该 voice\_id 将无法在 /v1/audio/speech 中继续使用，建议确认业务不再引用后再执行删除。

3.4.2 可能的错误码

错误码	说明
missing_id	请求体未提供 `id` 字段
invalid_voice_id	指定的 `id` 在当前组织下不存在或已被删除
server_error	内部错误或对象存储异常，可结合 `message` 与请求 ID 排查

完整生命周期说明

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

上传：调用 /v1/audio/voice/upload 上传音色音频，获取 voice\_id；
使用：在 /v1/audio/speech 接口中，将 voice 字段设置为上述 voice\_id；
管理：通过 /v1/audio/voice/list 查看可用音色，通过 /v1/audio/voice/delete 清理无效资源；
续期：注意 7 天有效期，超期前可重新上传音色以延续保存时长。

（注：文档部分内容可能由 AI 生成）