获取 TTS 音色列表

获取TTS音色列表

查询当前账号可用于对口型任务的 TTS 音色。接口返回音色 ID 和音色名称；创建对口型任务时，将选中的 speaker_id 填入 lip_sync_tts_speaker_id。

接口定位：辅助查询接口。仅用于获取音色，不会创建视频任务。

接入流程

获取 TTS 音色列表 -> 选择 speaker_id -> 创建对口型任务

如果对口型任务使用上传音频，可以跳过本接口。

请求 Header

Header	类型	是否必填	说明
`API-KEY`	string	是	PixVerse API Key。请放在 Header 中，不要放在 URL Query 中。
`Ai-trace-id`	string	是	请求追踪 ID。建议每次请求生成新的 UUID，便于问题排查。

Query 参数

所有 Query 参数均为可选。不传 Query 时，接口会返回当前账号可见的音色列表。

参数	类型	是否必填	枚举值 / 示例	说明
`page_num`	integer	否	`1`	页码。缺省或传 `0` 时取 `1`；有效页码从 `1` 开始，代码未设置最大值；负数返回 `400017`。
`page_size`	integer	否	`10`、`20`、`50`、`100`	每页数量。缺省或传 `0` 时取 `20`；仅允许四个枚举值，不是 `10–100` 的连续区间。
`speaker_type`	string	否	`system`、`custom`、`all`	音色类型，默认值为 `all`。

cURL 调试示例

分页并仅查询系统音色：

字段填写备注

字段	是否必填	枚举值 / 示例	填写建议
`API-KEY`	是	`your-api-key`	替换为控制台获取的正式 API Key。不要放在 URL Query、前端代码或公开文档中。
`Ai-trace-id`	是	`550e8400-e29b-41d4-a716-446655440000`	填写符合 UUID v4 格式的唯一值。建议每次请求生成新值，方便日志追踪和问题排查。
`page_num`	否	`1`	integer。缺省或传 `0` 时取 `1`；负数无效。
`page_size`	否	`10`、`20`、`50`、`100`	integer。缺省或传 `0` 时取 `20`，只能使用列出的四个值。
`speaker_type`	否	`system`、`custom`、`all`	按音色来源筛选。`system` 为系统音色，`custom` 为当前账号的自定义音色，`all` 为全部。
`Resp.data[].speaker_id`	响应字段	`Auto`、`14`、`6`、`13`、`2`、`4`、`12`、`11`、`10`、`16`、`18`、`19`、`20`、`21`	创建对口型任务时，将选中的值按字符串原样传入 `lip_sync_tts_speaker_id`。音色可能变化，以接口实时返回为准。
`Resp.data[].name`	响应字段	`随机`、`呆萌王小拍`、`李解`	仅用于展示音色名称，不要把名称当作 `speaker_id` 传入对口型接口。
`Resp.data[].speaker_type`	响应字段	`system`、`custom`	音色来源类型。该字段可能省略，客户端应按可选字段处理。
随机音色	响应枚举	`Auto`	区分大小写，应使用 `Auto`，不要使用 `auto`。

响应字段

字段	类型	说明
`ErrCode`	integer	业务错误码，`0` 表示成功。
`ErrMsg`	string	错误信息；成功时通常为 `Success`。
`Resp.total`	integer	接口返回的音色总数。
`Resp.data`	array	音色数据列表。
`Resp.data[].speaker_id`	string	音色 ID。创建对口型任务时传入 `lip_sync_tts_speaker_id`。
`Resp.data[].name`	string	音色展示名称。
`Resp.data[].speaker_type`	string	音色来源类型，当前可见值为 `system` 或 `custom`。该字段可能不返回。

成功响应示例

以下为国内环境实际请求返回的结构，HTTP 状态码为 200：

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "total": 14,
    "data": [
      {
        "speaker_id": "Auto",
        "name": "随机",
        "speaker_type": "system"
      },
      {
        "speaker_id": "14",
        "name": "呆萌王小拍",
        "speaker_type": "system"
      },
      {
        "speaker_id": "6",
        "name": "李解",
        "speaker_type": "system"
      },
      {
        "speaker_id": "13",
        "name": "钱多多",
        "speaker_type": "system"
      },
      {
        "speaker_id": "2",
        "name": "詹有鱼",
        "speaker_type": "system"
      },
      {
        "speaker_id": "4",
        "name": "外国阿利",
        "speaker_type": "system"
      },
      {
        "speaker_id": "12",
        "name": "李杰克",
        "speaker_type": "system"
      },
      {
        "speaker_id": "11",
        "name": "老森",
        "speaker_type": "system"
      },
      {
        "speaker_id": "10",
        "name": "姜姜好",
        "speaker_type": "system"
      },
      {
        "speaker_id": "16",
        "name": "屯里大嗓",
        "speaker_type": "system"
      },
      {
        "speaker_id": "18",
        "name": "豫语汉子",
        "speaker_type": "system"
      },
      {
        "speaker_id": "19",
        "name": "宝岛囡囡",
        "speaker_type": "system"
      },
      {
        "speaker_id": "20",
        "name": "陕西掌柜",
        "speaker_type": "system"
      },
      {
        "speaker_id": "21",
        "name": "港风阿sir",
        "speaker_type": "system"
      }
    ]
  }
}

在对口型任务中使用

例如选择“随机”音色时，应传入接口实际返回的大写 Auto：

{
  "video_media_id": 123456,
  "lip_sync_tts_speaker_id": "Auto",
  "lip_sync_tts_content": "你好，欢迎使用 PixVerse API。"
}

字段映射关系：

Resp.data[].speaker_id
        ↓
lip_sync_tts_speaker_id

请传递 speaker_id，不要将音色名称 name 传入对口型接口。

常见错误响应

以下为平台公共错误码，具体以接口实际返回为准：

`ErrCode`	说明	处理建议
`10005`	API Key 缺失、无效、过期或已撤销	检查 `API-KEY` Header，并确认密钥属于当前环境。
`400011`	参数为空	检查必填 Header 是否缺失。
`400013`	参数类型或值错误	检查 Header 格式和请求方式。
`400017`	参数无效	检查分页范围和 `speaker_type`。例如 `page_size=9` 会返回 `Invalid value for page_size.`。
`500020`	当前账号无权限	确认账号是否已开通相关 API 权限。
`500069`	系统负载过高	稍后重试，并保留 `Ai-trace-id` 便于排查。
`99999`	未知错误	记录完整响应和 `Ai-trace-id`，联系技术支持。

注意事项

speaker_id 的类型是字符串。即使返回值看起来是数字，也请按字符串传递，例如 "14"。

音色可能随平台配置变化，请以本接口的实时返回为准，不建议在业务中长期写死音色列表。

speaker_id 区分大小写；随机音色当前返回值为 Auto。

speaker_type 是可选响应字段，客户端不要因个别元素缺少该字段而解析失败。

本接口只查询音色，不会生成音频文件，也不会创建对口型任务。

HTTP 200 只表示请求已到达服务端，仍需检查 ErrCode 是否为 0。

音色列表可以短期缓存，但应定期刷新；音色创建失败时建议重新拉取列表。

下一步

选择 speaker_id 后，调用 POST /openapi/v2/video/lip_sync/generate 创建对口型任务。