# 查询公共音色列表

> 视频生成

获取系统提供的公共音色列表，用于 TTS 模式对口型

## 请求地址

`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. **TTS 模式** (`audio_type=\"tts\"`)\n   - 输入文本，系统合成语音驱动口型\n   - 需要：`audio_man_id` + `text`\n   - 可调节：speed（语速）、pitch（音调）\n\n2. **音频驱动模式** (`audio_type=\"audio\"`)\n   - 上传音频文件，直接驱动口型\n   - 需要：`audio_file_id`\n\n**完整流程：**\n1. 上传视频文件 → 获取 `video_file_id`\n2. （音频模式）上传音频文件 → 获取 `audio_file_id`\n3. （TTS模式）查询公共音色列表 → 获取 `audio_man_id`\n4. 提交对口型任务 → 获取 `task_id`\n5. 轮询查询任务状态 → 获取结果 URL\n\n**屏幕尺寸：**\n- `1080*1920` - 竖屏 9:16（默认）\n- `1920*1080` - 横屏 16:9\n- `720*1280` - 竖屏 9:16（小尺寸）\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 服务器"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/chanjing/list_common_audio": {
      "get": {
        "summary": "查询公共音色列表",
        "description": "获取系统提供的公共音色列表，用于 TTS 模式对口型",
        "operationId": "listChanjingCommonAudio",
        "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"
          }
        }
      }
    },
    "/v1/tasks/submit": {
      "post": {
        "summary": "提交对口型任务",
        "description": "提交视频对口型任务，支持 TTS 模式和音频驱动模式。\n\n**重要提示：**\n- `audio_type` 为必填字段，必须显式传入 `\"tts\"` 或 `\"audio\"`\n- TTS 模式：`audio_man_id` 和 `text` 必填\n- 音频模式：`audio_file_id` 必填\n",
        "operationId": "submitChanjingLipSyncTask",
        "tags": [
          "蝉镜对口型"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitLipSyncRequest"
              },
              "examples": {
                "ttsMode": {
                  "summary": "TTS 模式",
                  "value": {
                    "model": "cicada-video-lip-sync",
                    "input": {
                      "video_file_id": "file_video_xxx",
                      "audio_type": "tts",
                      "audio_man_id": "f9248f3b1b42447fb9282829321cfcf2",
                      "text": "你好，这是对口型测试"
                    },
                    "parameters": {
                      "model_version": "0",
                      "speed": 1,
                      "pitch": 1,
                      "volume": 100,
                      "size": "1080*1920"
                    }
                  }
                },
                "audioMode": {
                  "summary": "音频驱动模式",
                  "value": {
                    "model": "cicada-video-lip-sync",
                    "input": {
                      "video_file_id": "file_video_xxx",
                      "audio_type": "audio",
                      "audio_file_id": "file_audio_xxx"
                    },
                    "parameters": {
                      "model_version": "0",
                      "volume": 80,
                      "size": "1080*1920"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务提交成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitTaskResponse"
                },
                "example": {
                  "output": {
                    "task_id": "task_lip_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": "getChanjingLipSyncTaskStatus",
        "tags": [
          "蝉镜对口型"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "任务ID",
            "schema": {
              "type": "string"
            },
            "example": "task_lip_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "进行中",
                    "value": {
                      "output": {
                        "task_id": "task_lip_abc123",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "success": {
                    "summary": "成功",
                    "value": {
                      "output": {
                        "task_id": "task_lip_abc123",
                        "task_status": "Success",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500,
                        "urls": [
                          "https://xxx.oss-cn-beijing.aliyuncs.com/lip_sync_video.mp4"
                        ]
                      },
                      "usage": {
                        "duration": 15
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "failure": {
                    "summary": "失败",
                    "value": {
                      "output": {
                        "task_id": "task_lip_abc123",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500,
                        "error_message": "视频处理失败"
                      },
                      "request_id": "req_xxx"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API Key 认证，格式：Bearer {api_key}"
      }
    },
    "schemas": {
      "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": "每页数量"
          }
        }
      },
      "LipSyncInput": {
        "type": "object",
        "required": [
          "video_file_id",
          "audio_type"
        ],
        "properties": {
          "video_file_id": {
            "type": "string",
            "description": "视频文件ID（通过文件上传接口获取）"
          },
          "audio_type": {
            "type": "string",
            "description": "声音驱动类型",
            "enum": [
              "tts",
              "audio"
            ]
          },
          "audio_man_id": {
            "type": "string",
            "description": "系统音色ID（audio_type=\"tts\" 时必填）"
          },
          "audio_file_id": {
            "type": "string",
            "description": "音频文件ID（audio_type=\"audio\" 时必填）"
          },
          "text": {
            "type": "string",
            "description": "对口型文本内容（audio_type=\"tts\" 时必填）"
          }
        }
      },
      "LipSyncParameters": {
        "type": "object",
        "properties": {
          "model_version": {
            "type": "string",
            "description": "模型版本",
            "enum": [
              "0",
              "1"
            ],
            "default": "0"
          },
          "size": {
            "type": "string",
            "description": "屏幕尺寸，格式：宽度*高度",
            "default": "1080*1920"
          },
          "speed": {
            "type": "number",
            "format": "float",
            "description": "语速，范围 0.5-2.0，仅 TTS 模式生效",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "description": "音调，仅 TTS 模式生效",
            "default": 1
          },
          "volume": {
            "type": "integer",
            "description": "音量，范围 1-100",
            "default": 100,
            "minimum": 1,
            "maximum": 100
          }
        }
      },
      "SubmitLipSyncRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "模型名称",
            "enum": [
              "cicada-video-lip-sync"
            ]
          },
          "input": {
            "$ref": "#/components/schemas/LipSyncInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/LipSyncParameters"
          }
        }
      },
      "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": {
          "duration": {
            "type": "integer",
            "description": "生成视频时长，单位秒"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "$ref": "#/components/schemas/TaskStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/TaskUsage"
          },
          "request_id": {
            "type": "string",
            "description": "请求ID"
          }
        }
      },
      "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": {
              "missingAudioType": {
                "summary": "缺少 audio_type",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.audio_type is required for lip sync, must be 'tts' or 'audio'"
                  }
                }
              },
              "missingAudioManId": {
                "summary": "TTS模式缺少 audio_man_id",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.audio_man_id is required when audio_type is 'tts'"
                  }
                }
              },
              "missingText": {
                "summary": "TTS模式缺少 text",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.text is required when audio_type is 'tts'"
                  }
                }
              },
              "missingAudioFileId": {
                "summary": "音频模式缺少 audio_file_id",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.audio_file_id is required when audio_type is 'audio'"
                  }
                }
              }
            }
          }
        }
      },
      "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"
              }
            }
          }
        }
      }
    }
  }
}
```