# 查询定制音色任务状态

> 音频生成

查询定制音色任务的执行状态和结果。

**任务状态：**
- `Pending` - 任务进行中（制作中）
- `Success` - 任务成功完成（制作完成）
- `Failure` - 任务失败（制作失败）

## 请求地址

`GET https://api.modelverse.cn/v1/tasks/status`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | 任务ID（即 C-Audio-xxx） |

## 响应

- **200** — 任务状态获取成功
- **401** — 
- **404** — 

## OpenAPI 定义

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "ModelVerse 蝉镜定制音色 API",
    "description": "蝉镜定制音色接口，支持通过上传音频文件创建个性化音色。\n\n**使用流程：**\n1. 上传音频文件（通过文件管理接口）→ 获取音频文件 URL\n2. 提交定制音色任务 → 获取 `task_id`\n3. 轮询查询任务状态 → 获取 `voice_id`\n4. 后续可以使用该定制的音色 `voice_id` 进行语音合成\n\n**音频要求：**\n- 格式：MP3、WAV\n- 时长：建议 10-30 秒\n- 内容：清晰的人声，无背景噪音，单人说话\n\n**任务状态：**\n- `Pending` - 任务进行中（制作中）\n- `Success` - 任务成功完成（制作完成）\n- `Failure` - 任务失败（制作失败）\n\n**定制音色状态（查询任务状态/列表接口）：**\n- `0` - 等待制作\n- `1` - 制作中\n- `2` - 制作完成\n- `3` - 已过期\n- `4` - 制作失败\n- `99` - 已删除\n\n**模型类型说明：**\n- `cicada1.0` - 基础版本，支持方言\n- `cicada3.0` - 标准版本，不支持方言\n- `cicada3.0-turbo` - 快速版本，不支持方言\n\n**语种说明：**\n- `cn` - 中文\n- `en` - 英文\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- 音频文件需先通过文件管理接口上传获取 URL\n- 训练完成后返回的 `voice_id` 可用于语音合成\n- 必须使用 `cicada1.0` 模型生成的定制音色才能支持方言合成\n",
        "operationId": "submitChanjingCustomVoiceTask",
        "tags": [
          "蝉镜定制音色"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitCustomVoiceRequest"
              },
              "example": {
                "model": "cicada-customised-audio",
                "input": {
                  "url": "https://xxx.oss-cn-beijing.aliyuncs.com/audio/sample.mp3"
                },
                "parameters": {
                  "name": "我的定制音色",
                  "model_type": "cicada3.0",
                  "language": "cn",
                  "text": "你好，这是测试文本"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务提交成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitTaskResponse"
                },
                "example": {
                  "output": {
                    "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd"
                  },
                  "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": "getChanjingCustomVoiceTaskStatus",
        "tags": [
          "蝉镜定制音色"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "任务ID（即 C-Audio-xxx）",
            "schema": {
              "type": "string"
            },
            "example": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd"
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "训练中",
                    "value": {
                      "output": {
                        "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "success": {
                    "summary": "训练成功",
                    "value": {
                      "output": {
                        "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                        "task_status": "Success",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "failure": {
                    "summary": "训练失败",
                    "value": {
                      "output": {
                        "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                        "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"
          }
        }
      }
    },
    "/v1/chanjing/customised-audio": {
      "get": {
        "summary": "查询定制音色列表",
        "description": "获取当前用户的所有定制音色列表",
        "operationId": "listChanjingCustomVoices",
        "tags": [
          "蝉镜定制音色"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "页码，默认 1",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "每页数量，默认 10",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "定制音色列表获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceListResponse"
                },
                "example": {
                  "list": [
                    {
                      "id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                      "name": "我的定制音色",
                      "type": "cicada3.0",
                      "lang": "cn",
                      "progress": 100,
                      "audio_path": "https://xxx.oss-cn-beijing.aliyuncs.com/customised_audio.mp3",
                      "err_msg": "",
                      "status": 2
                    }
                  ],
                  "page_info": {
                    "page": 1,
                    "size": 10,
                    "total_count": 1,
                    "total_page": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/chanjing/customised-audio/{id}": {
      "delete": {
        "summary": "删除定制音色",
        "description": "删除指定的定制音色",
        "operationId": "deleteChanjingCustomVoice",
        "tags": [
          "蝉镜定制音色"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "定制音色ID",
            "schema": {
              "type": "string"
            },
            "example": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd"
          }
        ],
        "responses": {
          "200": {
            "description": "定制音色删除成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteCustomVoiceResponse"
                },
                "example": {
                  "code": 0,
                  "msg": "success"
                }
              }
            }
          },
          "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": {
      "CustomVoiceInput": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "音频文件URL（通过文件上传接口获取）"
          }
        }
      },
      "CustomVoiceParameters": {
        "type": "object",
        "required": [
          "name",
          "model_type",
          "language"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "定制音色名称"
          },
          "model_type": {
            "type": "string",
            "description": "模型类型",
            "enum": [
              "cicada1.0",
              "cicada3.0",
              "cicada3.0-turbo"
            ]
          },
          "language": {
            "type": "string",
            "description": "语种",
            "enum": [
              "cn",
              "en"
            ]
          },
          "text": {
            "type": "string",
            "description": "测试文本（可选）"
          }
        }
      },
      "SubmitCustomVoiceRequest": {
        "type": "object",
        "required": [
          "model",
          "input",
          "parameters"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "模型名称",
            "enum": [
              "cicada-customised-audio"
            ]
          },
          "input": {
            "$ref": "#/components/schemas/CustomVoiceInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/CustomVoiceParameters"
          }
        }
      },
      "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时间戳）"
          },
          "error_message": {
            "type": "string",
            "description": "错误信息（失败时返回）"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "$ref": "#/components/schemas/TaskStatusOutput"
          },
          "request_id": {
            "type": "string",
            "description": "请求ID"
          }
        }
      },
      "CustomVoiceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "定制音色ID"
          },
          "name": {
            "type": "string",
            "description": "定制音色名称"
          },
          "type": {
            "type": "string",
            "description": "模型类型"
          },
          "lang": {
            "type": "string",
            "description": "语种"
          },
          "progress": {
            "type": "integer",
            "description": "制作进度（0-100）"
          },
          "audio_path": {
            "type": "string",
            "description": "音频文件URL"
          },
          "err_msg": {
            "type": "string",
            "description": "错误信息"
          },
          "status": {
            "type": "integer",
            "description": "制作状态：\n- 0: 等待制作\n- 1: 制作中\n- 2: 制作完成\n- 3: 已过期\n- 4: 制作失败\n- 99: 已删除\n"
          }
        }
      },
      "PageInfo": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "当前页码"
          },
          "size": {
            "type": "integer",
            "description": "每页数量"
          },
          "total_count": {
            "type": "integer",
            "description": "总数"
          },
          "total_page": {
            "type": "integer",
            "description": "总页数"
          }
        }
      },
      "CustomVoiceListResponse": {
        "type": "object",
        "properties": {
          "list": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomVoiceItem"
            },
            "description": "定制音色列表"
          },
          "page_info": {
            "$ref": "#/components/schemas/PageInfo"
          }
        }
      },
      "CustomVoiceDetailResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "定制音色ID"
          },
          "name": {
            "type": "string",
            "description": "定制音色名称"
          },
          "type": {
            "type": "string",
            "description": "模型类型"
          },
          "lang": {
            "type": "string",
            "description": "语种"
          },
          "progress": {
            "type": "integer",
            "description": "制作进度（0-100）"
          },
          "audio_path": {
            "type": "string",
            "description": "音频文件URL"
          },
          "err_msg": {
            "type": "string",
            "description": "错误信息"
          },
          "status": {
            "type": "integer",
            "description": "制作状态：\n- 0: 等待制作\n- 1: 制作中\n- 2: 制作完成\n- 3: 已过期\n- 4: 制作失败\n- 99: 已删除\n"
          },
          "create_time": {
            "type": "integer",
            "description": "创建时间（Unix时间戳）"
          },
          "update_time": {
            "type": "integer",
            "description": "更新时间（Unix时间戳）"
          }
        }
      },
      "DeleteCustomVoiceResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "状态码，0 表示成功"
          },
          "msg": {
            "type": "string",
            "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": {
              "missingUrl": {
                "summary": "缺少 url",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "url is required"
                  }
                }
              },
              "missingName": {
                "summary": "缺少 name",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "name is required"
                  }
                }
              },
              "missingModelType": {
                "summary": "缺少 model_type",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "model_type is required"
                  }
                }
              },
              "missingLanguage": {
                "summary": "缺少 language",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "language is required"
                  }
                }
              }
            }
          }
        }
      },
      "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": "custom voice not found"
              }
            }
          }
        }
      }
    }
  }
}
```