> ## Documentation Index
> Fetch the complete documentation index at: https://www.qhaigc.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取角色列表

> 获取所有可用的语音角色名称和描述

## 功能说明

用于查询当前账号下所有可用的语音角色，包括系统内置角色和用户自定义克隆的角色。

## 请求方式

`GET /v1/voice/models/list`

## 调用示例

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.qhaigc.net/v1/voice/models/list"
  headers = {
      "Authorization": "sk-your-api-key-here"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl https://api.qhaigc.net/v1/voice/models/list \
    -H "Authorization: sk-your-api-key-here"
  ```
</CodeGroup>

## 返回结果

成功返回角色列表和总数。

<CodeGroup>
  ```json 响应示例 theme={null}
  {
    "success": true,
    "voice_characters": [
      {
        "name": "可爱少女",
        "public": "public",
        "description": "元气可爱的少女声音"
      },
      {
        "name": "御姐",
        "public": "public",
        "description": "成熟稳重的女性声音"
      }
      // ... 更多角色
    ],
    "total": 38
  }
  ```
</CodeGroup>

## 相关接口

* [文本转音频](/docs/api-reference/audio/speech)
* [创建语音角色（语音克隆）](/docs/api-reference/voice-clone/create-model)


## OpenAPI

````yaml GET /v1/voice/models/list
openapi: 3.1.0
info:
  title: 启航 AI API
  version: 1.0.0
  description: 启航 AI API 文档，支持绘图、语音生成、视频生成、音乐生成等多种 AIGC 接口。
servers:
  - url: https://api.qhaigc.net
    description: 生产服务器
security:
  - bearerAuth: []
paths:
  /v1/voice/models/list:
    get:
      tags:
        - 语音生成
      summary: 获取角色列表
      description: 获取所有可用的语音角色名称和描述
      responses:
        '200':
          description: 角色列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  voice_characters:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        public:
                          type: string
                        description:
                          type: string
                  total:
                    type: integer
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````