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

# 系统音色列表

> 列出系统预设音色。把 `voiceId`（`sv_*`）用于 `voiceSpeakers.selectedVoicesList`。



## OpenAPI

````yaml /zh/api-reference/app-synced.json post /openapi/v1/app/assets/voice/basic/list
openapi: 3.1.0
info:
  title: VMEG 开放 API（应用同源版）
  description: >-
    与独立版协议一致，但任务、素材、克隆音色都在你的 VMEG 网站账号里：任务出现在**我的任务**，可在编辑器继续编辑并重新导出。结果通过轮询 `GET
    /openapi/v1/app/tasks/detail` 获取（无
    Webhook）。见[独立版与应用同源版的区别](/zh/guides/app-synced/comparison)。


    文中链接的指南按独立版编写，步骤相同，把路径前缀 `/openapi/v1` 换成 `/openapi/v1/app` 即可。
  version: 1.0.0
servers:
  - url: https://api.vmeg.ai
    description: 生产环境
security:
  - apiKeyAuth: []
tags:
  - name: 媒体翻译
    x-group: 视频与音频翻译配音
    description: >-
      在与 vmeg.ai 相同的链路上翻译配音已上传的视频/音频或 YouTube
      链接。首轮即产出配音成片，任务同时出现在**我的任务**，可继续编辑并重新导出。结果请轮询[查询任务状态](/zh/api-reference/app-synced/tasks/get-task-detail)。
  - name: 声音克隆
    x-group: 声音克隆
    description: 用一段短录音克隆音色。音色保存到网站**我的音色**，返回 `cv_*`，可用于翻译配音任务。
  - name: 任务管理
    x-group: 任务状态与历史
    description: 列出、查看或删除你 VMEG 账号下的视频/音频翻译任务，包括在网站创建的任务。
  - name: 资产 - 素材
    x-group: 上传文件（素材）
    description: 上传并管理网站素材库（**我的资产**）里的文件。完成上传（单文件或分片）后，把 `materialId` 传给 create-async。
  - name: 资产 - 音色
    x-group: 音色（预设与克隆）
    description: 列出系统预设音色（`sv_*`），管理你的克隆音色（`cv_*`，与网站**我的音色**相同）。
paths:
  /openapi/v1/app/assets/voice/basic/list:
    post:
      tags:
        - 资产 - 音色
      summary: 系统音色列表
      description: 列出系统预设音色。把 `voiceId`（`sv_*`）用于 `voiceSpeakers.selectedVoicesList`。
      operationId: appVoiceBasicList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiBasicVoiceListRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiBasicVoiceListResponse'
components:
  schemas:
    OpenApiBasicVoiceListRequest:
      type: object
      properties:
        voiceId:
          type: string
          description: 按系统预设 `voiceId` 筛选。见 [音色](/zh/guides/app-synced/comparison)
        searchName:
          type: string
          description: 按展示名或本地化名称搜索
        locale:
          type: string
          example: en-US
          description: 按 locale（BCP-47）筛选。见 [支持的语言](/zh/guides/supported-languages)
        age:
          type: string
          description: young / adult / senior
        gender:
          type: string
          description: 按性别筛选
        quality:
          type: string
          description: any / high
        category:
          type: string
          description: 按音色分类筛选
        emotionPrompt:
          type: string
          description: exclude / include
        topIds:
          type: array
          items:
            type: string
          description: 将这些系统预设 `voiceId` 置顶。见 [音色](/zh/guides/app-synced/comparison)
        currentPage:
          type: integer
          default: 1
          description: 页码（从 1 开始）
        pageSize:
          type: integer
          default: 10
          description: 每页条数
        orderBy:
          type: string
          description: voiceId / score / create_time / update_time / is_preferred
        order:
          type: string
          default: desc
          description: 排序方向：`asc` 或 `desc`
    OpenApiBasicVoiceListResponse:
      allOf:
        - $ref: '#/components/schemas/OpenApiResponseBase'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/OpenApiBasicVoiceListData'
    OpenApiResponseBase:
      type: object
      properties:
        code:
          type: integer
          example: 200
          description: 业务码；200 表示成功
        message:
          type: string
          example: ''
          description: 当 `code` 非成功时的说明信息
      required:
        - code
    OpenApiBasicVoiceListData:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiBasicVoiceDto'
          description: 本页音色列表
        total:
          type: integer
          format: int64
          description: 符合筛选条件的音色总数
    OpenApiBasicVoiceDto:
      type: object
      properties:
        voiceId:
          type: string
          description: 系统预设音色 ID。见 [音色](/zh/guides/app-synced/comparison)
        localName:
          type: string
          description: 本地化名称
        displayName:
          type: string
          description: 音色选择器中的展示名
        locale:
          type: string
          example: en-US
          description: 该预设的主 locale（BCP-47）
        localeName:
          type: string
          description: locale 的可读名称
        provider:
          type: string
          description: 预设档位代号（`S1`–`S7`）。见 [支持的克隆方式](/zh/guides/supported-clone-methods)。
        gender:
          type: string
          description: 性别标签（如 male、female）
        style:
          type: string
          description: 说话风格标签
        rolePlay:
          type: string
          description: 角色扮演/人设标签
        description:
          type: string
          description: Marketing or catalog description
        personalities:
          type: string
          description: 人格标签（逗号分隔）
        personalityList:
          type: array
          items:
            type: string
          description: 人格标签列表
        scenarios:
          type: string
          description: 推荐使用场景标签
        scenarioList:
          type: array
          items:
            type: string
          description: 场景标签列表
        isHd:
          type: integer
          description: 高清音色时为 `1`
        isPreferred:
          type: integer
          description: 目录中标记为优选时为 `1`
        score:
          type: number
          description: 列表排序得分
        cover:
          type: string
          description: 封面图 URL（HTTPS）。请原样使用 API 返回的地址。
        audio:
          type: string
          description: 试听音频 URL（HTTPS）。请原样使用 API 返回的地址。
        createTime:
          type: string
          description: 记录创建时间
        updateTime:
          type: string
          description: 记录最近更新时间
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        在 **`Authorization`** 请求头中传入 API Key（`Bearer <api_key>`）。见
        [鉴权](/zh/guides/authentication)。

````