# Submit Custom Voice Task

> Audio Generation

Submit a custom voice training task.

**Notes:**
- Audio file must be uploaded via file management API to get URL first
- The `voice_id` returned after training can be used for voice synthesis
- Must use `cicada1.0` model generated custom voice to support dialect synthesis

## Endpoint

`POST https://api.modelverse.cn/v1/tasks/submit`

## Request Body

## Responses

- **200** — Task submitted successfully
- **400** — 
- **401** — 

## OpenAPI Definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "ModelVerse Chanjing Custom Voice API",
    "description": "Chanjing custom voice API for creating personalized voices by uploading audio files.\n\n**Usage Workflow:**\n1. Upload audio file (via file management API) → Get audio file URL\n2. Submit custom voice training task → Get `task_id`\n3. Poll task status → Get `voice_id`\n4. Use `voice_id` for voice synthesis\n\n**Audio Requirements:**\n- Format: MP3, WAV\n- Duration: Recommended 10-30 seconds\n- Content: Clear human voice, no background noise, single speaker\n\n**Task Status:**\n- `Pending` - Task in progress (producing)\n- `Success` - Task completed successfully (production completed)\n- `Failure` - Task failed (production failed)\n\n**Custom Voice Status (List API):**\n- `0` - Waiting for production\n- `1` - In production\n- `2` - Production completed\n- `3` - Expired\n- `4` - Production failed\n- `99` - Deleted\n\n**Model Type Description:**\n- `cicada1.0` - Basic version, supports dialects\n- `cicada3.0` - Standard version, does not support dialects\n- `cicada3.0-turbo` - Fast version, does not support dialects\n\n**Language Description:**\n- `cn` - Chinese\n- `en` - English\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API Server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "summary": "Submit Custom Voice Task",
        "description": "Submit a custom voice training task.\n\n**Notes:**\n- Audio file must be uploaded via file management API to get URL first\n- The `voice_id` returned after training can be used for voice synthesis\n- Must use `cicada1.0` model generated custom voice to support dialect synthesis\n",
        "operationId": "submitChanjingCustomVoiceTask",
        "tags": [
          "Chanjing Custom Voice"
        ],
        "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": "My Custom Voice",
                  "model_type": "cicada3.0",
                  "language": "cn",
                  "text": "Hello, this is a test text"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully",
            "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": "Get Custom Voice Task Status",
        "description": "Query the execution status and result of a custom voice task.\n\n**Task Status:**\n- `Pending` - Task in progress (producing)\n- `Success` - Task completed successfully (production completed)\n- `Failure` - Task failed (production failed)\n",
        "operationId": "getChanjingCustomVoiceTaskStatus",
        "tags": [
          "Chanjing Custom Voice"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Task ID (i.e., C-Audio-xxx)",
            "schema": {
              "type": "string"
            },
            "example": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "In progress",
                    "value": {
                      "output": {
                        "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "success": {
                    "summary": "Training successful",
                    "value": {
                      "output": {
                        "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                        "task_status": "Success",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "failure": {
                    "summary": "Training failed",
                    "value": {
                      "output": {
                        "task_id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500,
                        "error_message": "Audio quality does not meet requirements"
                      },
                      "request_id": "req_xxx"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/chanjing/customised-audio": {
      "get": {
        "summary": "List Custom Voices",
        "description": "Get all custom voices for the current user",
        "operationId": "listChanjingCustomVoices",
        "tags": [
          "Chanjing Custom Voice"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, default 1",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Items per page, default 10",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Custom voice list retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomVoiceListResponse"
                },
                "example": {
                  "list": [
                    {
                      "id": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd",
                      "name": "My Custom Voice",
                      "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": "Delete Custom Voice",
        "description": "Delete a specific custom voice",
        "operationId": "deleteChanjingCustomVoice",
        "tags": [
          "Chanjing Custom Voice"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Custom Voice ID",
            "schema": {
              "type": "string"
            },
            "example": "C-Audio-1a6050b2e7cd4ff88168d5c7c12a45bd"
          }
        ],
        "responses": {
          "200": {
            "description": "Custom voice deleted successfully",
            "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 authentication, format: Bearer {api_key}"
      }
    },
    "schemas": {
      "CustomVoiceInput": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio file URL (obtained via file upload API)"
          }
        }
      },
      "CustomVoiceParameters": {
        "type": "object",
        "required": [
          "name",
          "model_type",
          "language"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Custom voice name"
          },
          "model_type": {
            "type": "string",
            "description": "Model type",
            "enum": [
              "cicada1.0",
              "cicada3.0",
              "cicada3.0-turbo"
            ]
          },
          "language": {
            "type": "string",
            "description": "Language",
            "enum": [
              "cn",
              "en"
            ]
          },
          "text": {
            "type": "string",
            "description": "Test text (optional)"
          }
        }
      },
      "SubmitCustomVoiceRequest": {
        "type": "object",
        "required": [
          "model",
          "input",
          "parameters"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name",
            "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": "Task ID"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Request ID"
          }
        }
      },
      "TaskStatusOutput": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Task ID"
          },
          "task_status": {
            "type": "string",
            "description": "Task status",
            "enum": [
              "Pending",
              "Success",
              "Failure"
            ]
          },
          "submit_time": {
            "type": "integer",
            "description": "Submission time (Unix timestamp)"
          },
          "finish_time": {
            "type": "integer",
            "description": "Completion time (Unix timestamp)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (returned when failed)"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "$ref": "#/components/schemas/TaskStatusOutput"
          },
          "request_id": {
            "type": "string",
            "description": "Request ID"
          }
        }
      },
      "CustomVoiceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Custom voice ID"
          },
          "name": {
            "type": "string",
            "description": "Custom voice name"
          },
          "type": {
            "type": "string",
            "description": "Model type"
          },
          "lang": {
            "type": "string",
            "description": "Language"
          },
          "progress": {
            "type": "integer",
            "description": "Production progress (0-100)"
          },
          "audio_path": {
            "type": "string",
            "description": "Audio file URL"
          },
          "err_msg": {
            "type": "string",
            "description": "Error message"
          },
          "status": {
            "type": "integer",
            "description": "Production status:\n- 0: Waiting for production\n- 1: In production\n- 2: Production completed\n- 3: Expired\n- 4: Production failed\n- 99: Deleted\n"
          }
        }
      },
      "PageInfo": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "size": {
            "type": "integer",
            "description": "Items per page"
          },
          "total_count": {
            "type": "integer",
            "description": "Total count"
          },
          "total_page": {
            "type": "integer",
            "description": "Total pages"
          }
        }
      },
      "CustomVoiceListResponse": {
        "type": "object",
        "properties": {
          "list": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomVoiceItem"
            },
            "description": "Custom voice list"
          },
          "page_info": {
            "$ref": "#/components/schemas/PageInfo"
          }
        }
      },
      "CustomVoiceDetailResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Custom voice ID"
          },
          "name": {
            "type": "string",
            "description": "Custom voice name"
          },
          "type": {
            "type": "string",
            "description": "Model type"
          },
          "lang": {
            "type": "string",
            "description": "Language"
          },
          "progress": {
            "type": "integer",
            "description": "Production progress (0-100)"
          },
          "audio_path": {
            "type": "string",
            "description": "Audio file URL"
          },
          "err_msg": {
            "type": "string",
            "description": "Error message"
          },
          "status": {
            "type": "integer",
            "description": "Production status:\n- 0: Waiting for production\n- 1: In production\n- 2: Production completed\n- 3: Expired\n- 4: Production failed\n- 99: Deleted\n"
          },
          "create_time": {
            "type": "integer",
            "description": "Creation time (Unix timestamp)"
          },
          "update_time": {
            "type": "integer",
            "description": "Update time (Unix timestamp)"
          }
        }
      },
      "DeleteCustomVoiceResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Status code, 0 means success"
          },
          "msg": {
            "type": "string",
            "description": "Status message"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error message"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingUrl": {
                "summary": "Missing url",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "url is required"
                  }
                }
              },
              "missingName": {
                "summary": "Missing name",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "name is required"
                  }
                }
              },
              "missingModelType": {
                "summary": "Missing model_type",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "model_type is required"
                  }
                }
              },
              "missingLanguage": {
                "summary": "Missing language",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "language is required"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "missing token"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "custom voice not found"
              }
            }
          }
        }
      }
    }
  }
}
```