API 文档音色管理
查询音色
查询当前 API 密钥可用的公开音色和个人音色。
查询音色
GET /api/open/v1/voices完整地址：
https://fishaudio.org/api/open/v1/voices请求头
Authorization: Bearer YOUR_API_KEY音色列表是只读接口，不会创建任务，也不会消耗积分。
查询参数
该接口从 URL query 读取筛选条件；不传参数时返回第一页公开音色。
| 参数 | 类型 | 说明 |
|---|---|---|
page | integer | 可选。页码，默认 1 |
pageSize | integer | 可选。每页数量，默认 20，最大 100 |
modelType | string | 可选。public、personal 或 all |
includePersonal | boolean | 可选。为 true 时默认返回个人音色和公开音色集合 |
不传参数时返回公开音色列表。具体数量和可见范围由账户权限和服务端配置决定。
响应
{
"total": 1,
"page": 1,
"pageSize": 20,
"totalPages": 1,
"items": [
{
"voiceId": "voice_123",
"title": "Clara",
"description": "",
"created_at": "2026-07-09T00:00:00.000Z",
"updated_at": "2026-07-09T00:00:00.000Z",
"isPersonal": false
}
]
}| 字段 | 说明 |
|---|---|
items[].voiceId | 音色 ID。后续 TTS 请求中使用 |
items[].title | 音色名称 |
isPersonal | 是否为当前账户的个人音色 |
total | 当前筛选条件下的总数量 |
curl 示例
curl "https://fishaudio.org/api/open/v1/voices?page=1&pageSize=20&modelType=public" \
-H "Authorization: Bearer YOUR_API_KEY"同步 TTS 通常只需要返回的 voiceId：
{
"text": "你好，欢迎使用 Fish Audio。",
"voiceId": "voice_123"
}错误行为
| 状态码 | 场景 |
|---|---|
401 | API 密钥缺失或无效 |
403 | 当前账户无权读取音色列表 |
500 | 音色目录查询失败 |