Agent 平台音色资源接口用于管理系统音色和项目空间内的个人音色。接口需要携带平台 JWT 鉴权。
一、获取音色列表
- 接口路径:
/api/v1/agents/resources/voices
- 请求方法:
GET
- 鉴权方式:
Authorization: Bearer <access_token>
Query 参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| language | string | 否 | 按主语言筛选音色。音色选择页当前展示 zh-CN、en-US；不传时返回全部可见音色 |
响应字段
| 字段 | 类型 | 说明 |
|---|
| items | array | 音色列表 |
| items[].id | string | 音色资源 ID |
| items[].voiceId | string | 业务音色 ID |
| items[].source | string | 音色来源，系统音色为 system_voice，个人音色为 cloned_voice |
| items[].name | string | 音色名称 |
| items[].description | string | 音色描述 |
| items[].language | string | 主语言，例如 zh-CN、en-US |
| items[].status | string | 音色状态 |
| items[].bindable | boolean | 是否可被 Agent 绑定 |
| items[].mutable | boolean | 是否允许当前项目页修改 |
二、创建个人音色
- 接口路径:
/api/v1/agents/resources/voices
- 请求方法:
POST
- 鉴权方式:
Authorization: Bearer <access_token>
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|
| name | string | 是 | 音色名称 |
| language | string | 否 | 主语言。为空时默认为中文 zh-CN |
| voiceId | string | 否 | 指定业务音色 ID；通常无需填写，由接口自动生成 |
| description | string | 否 | 音色描述 |
| avatarUrl | string | 否 | 音色头像 URL |
| sampleObjectKey | string | 否 | 克隆样本对象 Key |
| sampleTranscript | string | 否 | 克隆样本文本 |
| previewUrl | string | 否 | 试听音频 URL |
三、更新个人音色
- 接口路径:
/api/v1/agents/resources/voices/update
- 请求方法:
PATCH
- 鉴权方式:
Authorization: Bearer <access_token>
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|
| voiceId | string | 是 | 要更新的业务音色 ID |
| language | string | 否 | 更新主语言。为空时不修改已有语言 |
| name | string | 否 | 音色名称 |
| description | string | 否 | 音色描述 |
| avatarUrl | string | 否 | 音色头像 URL |
| resubmitSample | boolean | 否 | 是否重新提交克隆样本 |
| sampleObjectKey | string | 否 | 新克隆样本对象 Key |
| sampleTranscript | string | 否 | 新克隆样本文本 |
| previewUrl | string | 否 | 新试听音频 URL |
- 系统音色只读，不能通过创建、更新、删除接口修改。
- Agent 编辑页选择音色时，应按当前 Agent 的语言带上
language 查询参数，只展示同语言音色，并在音色卡片展示语言标签。