# 查询公共音色列表

> 音频生成

获取系统提供的公共音色列表

## 请求地址

`GET https://api.modelverse.cn/v1/chanjing/list_common_audio`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No | 页码，默认 1 |
| size | query | integer | No | 每页数量，默认 10 |

## 响应

- **200** — 音色列表获取成功
- **401** — 

## OpenAPI 定义

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "ModelVerse 蝉镜语音合成 API",
    "description": "蝉镜语音合成接口，支持标准语音合成、方言合成和口音转换三种模式。\n\n**三种合成模式：**\n\n1. **标准语音合成**（默认）\n   - 使用系统音色或定制音色进行语音合成\n   - 参数：`voice_id` + `text`\n\n2. **方言合成**（`dialect` 参数）\n   - 使用 cicada1.0 定制音色进行方言合成\n   - 参数：`voice_id`（C-Audio-xxx）+ `text` + `dialect`\n   - 支持 12 种方言\n\n3. **口音合成**（`prompt_audio` 参数）\n   - 使用参考音频进行口音合成\n   - 参数：`voice_id` + `text` + `prompt_audio` + `mss`\n\n\n**方言类型（dialect）：**\n| 值 | 方言 |\n|----|------|\n| 0 | 其他（默认） |\n| 1 | 东北话 |\n| 2 | 关中话 |\n| 3 | 江淮官话 |\n| 5 | 冀鲁官话 |\n| 6 | 青海话 |\n| 7 | 吴语 |\n| 8 | 天津话 |\n| 9 | 西南官话 |\n| 10 | 中原官话 |\n| 11 | 粤语 |\n| 12 | 闽南语 |\n\n**口音声音人ID列表：**\n| 声音人名称 | 模型 | 口音id |\n|------------|------|--------|\n| 四川男年轻 | cicada3.0-turbo | 89843d52ccd04e2d854decd28d6143ce |\n| 南京男年轻 | cicada3.0-turbo | b9705cff084c4416b02f01d797025c25 |\n| 陕西男年轻 | cicada3.0-turbo | f28c22c6d26f48f29ee4cc1380adff24 |\n| 天津年轻男 | cicada3.0-turbo | 2c9f4ce01f254b5e9408e5af3b464900 |\n| 天津年迈女 | cicada3.0-turbo | eb370cde929049d9b36debcb6161f053 |\n| 东北年轻男 | cicada3.0-turbo | 4027dfc73c6e4235911dba293f53e62f |\n| 台湾口音男 | cicada3.0-turbo | 63dd6a2bf2c54cbe828154f393e5d833 |\n| 闽南口音女 | cicada3.0-turbo | 1880b61fc567431aafe35266057a6585 |\n| 北京年轻男 | cicada3.0-turbo | 8a18396b48b54d5f8d4143369145d357 |\n| 东北年迈女 | cicada3.0-turbo | ed5eea52f94045198e9ec7c45e54fb96 |\n| 河南年迈女 | cicada3.0-turbo | 737b5b61343640139f539767c03be495 |\n| 四川年轻女 | cicada3.0-turbo | 74afc28ab43544669f50773449acf2b5 |\n\n**使用流程：**\n1. 准备音色：\n   - 标准合成：使用系统音色或定制音色\n   - 方言合成：使用 cicada1.0 定制音色\n   - 口音转换：上传参考音频文件获取 file_id\n2. 提交语音合成任务 → 获取 `task_id`\n3. 轮询查询任务状态 → 获取音频 URL\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 服务器"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "summary": "提交语音合成任务",
        "description": "提交语音合成任务，支持标准合成、方言合成和口音转换。\n\n**模式说明：**\n- **标准合成**：`voice_id` + `text`\n- **方言合成**：`voice_id`（C-Audio-xxx）+ `text` + `dialect`\n- **口音转换**：`voice_id` + `text` + `prompt_audio` + `mss`\n",
        "operationId": "submitChanjingTtsTask",
        "tags": [
          "蝉镜语音合成"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitTtsRequest"
              },
              "examples": {
                "standardTts": {
                  "summary": "标准语音合成",
                  "value": {
                    "model": "cicada-tts",
                    "input": {
                      "text": "你好，这是语音合成测试"
                    },
                    "parameters": {
                      "voice_id": "f9248f3b1b42447fb9282829321cfcf2",
                      "speed": 1,
                      "pitch": 1
                    }
                  }
                },
                "dialectTts": {
                  "summary": "方言合成",
                  "value": {
                    "model": "cicada-tts",
                    "input": {
                      "text": "你好，这是方言合成测试"
                    },
                    "parameters": {
                      "voice_id": "C-Audio-xxx",
                      "speed": 1,
                      "pitch": 1,
                      "dialect": 1
                    }
                  }
                },
                "accentTts": {
                  "summary": "口音转换",
                  "value": {
                    "model": "cicada-tts",
                    "input": {
                      "text": "你好，这是口音转换测试"
                    },
                    "parameters": {
                      "voice_id": "f9248f3b1b42447fb9282829321cfcf2",
                      "speed": 1,
                      "pitch": 1,
                      "prompt_audio": "09eacb8ead0a423e9dcd75065ae32d25",
                      "mss": 10
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务提交成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitTaskResponse"
                },
                "example": {
                  "output": {
                    "task_id": "task_tts_abc123"
                  },
                  "request_id": "req_xxx"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "summary": "查询语音合成任务状态",
        "description": "查询语音合成任务的执行状态和结果。\n\n**任务状态：**\n- `Pending` - 任务进行中\n- `Success` - 任务成功完成\n- `Failure` - 任务失败\n",
        "operationId": "getChanjingTtsTaskStatus",
        "tags": [
          "蝉镜语音合成"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "任务ID",
            "schema": {
              "type": "string"
            },
            "example": "task_tts_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "进行中",
                    "value": {
                      "output": {
                        "task_id": "task_tts_abc123",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "success": {
                    "summary": "成功",
                    "value": {
                      "output": {
                        "task_id": "task_tts_abc123",
                        "task_status": "Success",
                        "submit_time": 1704067200,
                        "finish_time": 1704067250,
                        "urls": [
                          "https://xxx.oss-cn-beijing.aliyuncs.com/tts_audio.mp3"
                        ]
                      },
                      "usage": {
                        "audio_duration": 3
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "failure": {
                    "summary": "失败",
                    "value": {
                      "output": {
                        "task_id": "task_tts_abc123",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067250,
                        "error_message": "语音合成失败"
                      },
                      "request_id": "req_xxx"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/chanjing/list_common_audio": {
      "get": {
        "summary": "查询公共音色列表",
        "description": "获取系统提供的公共音色列表",
        "operationId": "listChanjingCommonAudioForTts",
        "tags": [
          "蝉镜语音合成"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "页码，默认 1",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "每页数量，默认 10",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "音色列表获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonAudioListResponse"
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "f9248f3b1b42447fb9282829321cfcf2",
                      "name": "带货小芸",
                      "gender": "female",
                      "lang": "multilingual"
                    },
                    {
                      "id": "a1b2c3d4e5f678901234567890123456",
                      "name": "新闻主播",
                      "gender": "male",
                      "lang": "cn"
                    }
                  ],
                  "total": 91,
                  "page": 1,
                  "size": 10
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API Key 认证，格式：Bearer {api_key}"
      }
    },
    "schemas": {
      "TtsInput": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "要合成的文本内容，限制4000字",
            "maxLength": 4000
          }
        }
      },
      "TtsParameters": {
        "type": "object",
        "required": [
          "voice_id"
        ],
        "properties": {
          "voice_id": {
            "type": "string",
            "description": "音色ID：\n- 系统音色：从公共音色列表获取\n- 定制音色：C-Audio-xxx 格式\n"
          },
          "speed": {
            "type": "number",
            "format": "float",
            "description": "语速，范围 0.5-2.0",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "description": "音调，范围 0.5-2.0",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2
          },
          "dialect": {
            "type": "integer",
            "description": "方言类型（方言合成时使用）：\n- 0: 其他（默认）\n- 1: 东北话\n- 2: 关中话\n- 3: 江淮官话\n- 5: 冀鲁官话\n- 6: 青海话\n- 7: 吴语\n- 8: 天津话\n- 9: 西南官话\n- 10: 中原官话\n- 11: 粤语\n- 12: 闽南语\n",
            "minimum": 0,
            "maximum": 12
          },
          "prompt_audio": {
            "type": "string",
            "description": "音色prompt文件ID（口音合成时必填）"
          },
          "mss": {
            "type": "integer",
            "description": "AI断句字数，必须大于0（口音合成时必填）",
            "minimum": 1
          },
          "callback_url": {
            "type": "string",
            "description": "回调URL"
          }
        }
      },
      "SubmitTtsRequest": {
        "type": "object",
        "required": [
          "model",
          "input",
          "parameters"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "模型名称",
            "enum": [
              "cicada-tts"
            ]
          },
          "input": {
            "$ref": "#/components/schemas/TtsInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/TtsParameters"
          }
        }
      },
      "SubmitTaskResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "任务ID"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "请求ID"
          }
        }
      },
      "TaskStatusOutput": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "任务ID"
          },
          "task_status": {
            "type": "string",
            "description": "任务状态",
            "enum": [
              "Pending",
              "Success",
              "Failure"
            ]
          },
          "submit_time": {
            "type": "integer",
            "description": "提交时间（Unix时间戳）"
          },
          "finish_time": {
            "type": "integer",
            "description": "完成时间（Unix时间戳）"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "结果音频URL列表"
          },
          "error_message": {
            "type": "string",
            "description": "错误信息（失败时返回）"
          }
        }
      },
      "TaskUsage": {
        "type": "object",
        "properties": {
          "audio_duration": {
            "type": "integer",
            "description": "音频时长，单位秒"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "$ref": "#/components/schemas/TaskStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/TaskUsage"
          },
          "request_id": {
            "type": "string",
            "description": "请求ID"
          }
        }
      },
      "CommonAudioItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "音色ID"
          },
          "name": {
            "type": "string",
            "description": "音色名称"
          },
          "gender": {
            "type": "string",
            "description": "性别",
            "enum": [
              "male",
              "female"
            ]
          },
          "lang": {
            "type": "string",
            "description": "语言"
          }
        }
      },
      "CommonAudioListResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "description": "对象类型"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommonAudioItem"
            },
            "description": "音色列表"
          },
          "total": {
            "type": "integer",
            "description": "总数"
          },
          "page": {
            "type": "integer",
            "description": "当前页码"
          },
          "size": {
            "type": "integer",
            "description": "每页数量"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "错误码"
              },
              "message": {
                "type": "string",
                "description": "错误信息"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求参数错误",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingVoiceId": {
                "summary": "缺少 voice_id",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "voice_id is required"
                  }
                }
              },
              "missingText": {
                "summary": "缺少 text",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "text is required"
                  }
                }
              },
              "invalidDialect": {
                "summary": "无效的方言类型",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "dialect must be between 0 and 12"
                  }
                }
              },
              "textTooLong": {
                "summary": "文本过长",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "text exceeds maximum length of 4000 characters"
                  }
                }
              },
              "missingMss": {
                "summary": "口音合成缺少 mss",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "mss is required for accent TTS and must be greater than 0"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "认证失败",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "missing token"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "资源不存在",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "task not found"
              }
            }
          }
        }
      }
    }
  }
}
```