音色

当前 CN /v1 公开 API 只提供音色列表查询。它用于在 TTS 请求前获取可用 voiceId、默认模型、支持模型和语言信息。

创建、更新、查看单个音色详情或删除音色不属于当前公开 CN /v1 合同。如果你的产品需要管理自定义音色，请使用站内产品能力或等待公开合同扩展，不要在 SDK 中假设这些管理接口存在。

Endpoint

GET /v1/voices

完整地址：

https://kittaaudio.com/api/v1/voices

鉴权与请求头

Authorization: Bearer YOUR_API_TOKEN

音色列表是只读接口，不会创建任务，也不会消耗积分。

查询参数

GET /v1/voices?kind=system

参数	类型	说明
`kind`	string	可选。按音色类型筛选：`system`、`designed`、`cloned`

不传 kind 时返回当前 token 可访问的默认列表。具体数量和可见范围由账户权限和服务端配置决定。

响应

成功响应：

{
  "data": [
    {
      "id": "voice_123",
      "voiceId": "clara",
      "object": "voice",
      "name": "Clara",
      "displayName": {
        "zh-CN": "Clara",
        "en": "Clara"
      },
      "description": null,
      "kind": "system",
      "primaryLanguage": "zh",
      "supportedLanguages": ["zh", "en"],
      "languages": ["zh", "en"],
      "gender": "female",
      "voiceFamily": "clara",
      "defaultModel": "kitta-tts-v1",
      "supportedModels": ["kitta-tts-v1"],
      "modelFamilies": [
        {
          "family": "clara",
          "defaultModel": "kitta-tts-v1",
          "models": ["kitta-tts-v1"]
        }
      ],
      "avatarUrl": null
    }
  ]
}

字段说明：

字段	说明
`voiceId`	TTS 请求中的 `voiceId`
`kind`	音色类型，例如 `system`、`designed`、`cloned`
`defaultModel`	推荐搭配的默认 TTS 模型
`supportedModels`	该音色支持的 TTS 模型列表
`supportedLanguages` / `languages`	支持语言
`modelFamilies`	同一音色家族下的模型分组

curl 示例

curl -X GET "https://kittaaudio.com/api/v1/voices?kind=system" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

把返回的 voiceId 和 defaultModel 用于同步或异步 TTS：

{
  "text": "你好，欢迎使用 Kitta Audio。",
  "voiceId": "clara",
  "model": "kitta-tts-v1"
}

错误行为

错误响应示例：

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API token",
    "requestId": "req_xxx"
  }
}

状态码	场景
`401`	API Token 缺失或无效
`403`	当前账户无权读取音色列表
`500`	音色目录查询失败

kind 值不在 system、designed、cloned 中时，服务端可能按参数错误处理。客户端应使用枚举控件或 SDK 类型约束避免传错。

计费与积分

GET /v1/voices 不消耗积分。真正扣费发生在使用 voiceId 创建 TTS 音频时。建议定期缓存音色列表，但不要永久缓存模型能力；服务端可能调整某个音色支持的模型或语言。

接入建议

启动或用户打开选择器时调用 GET /v1/voices。
在 UI 中展示 name、displayName、kind 和语言。
提交 TTS 时传 voiceId 和一个 supportedModels 中的模型。
如果 TTS 返回模型不支持错误，刷新音色列表后再让用户重新选择。

音色

On this page