# Get TTS Task Status

> Audio Generation

Query the execution status and result of a TTS task.

**Task Status:**
- `Pending` - Task in progress
- `Success` - Task completed successfully
- `Failure` - Task failed

## Endpoint

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | Task ID |

## Responses

- **200** — Task status retrieved successfully
- **401** — 
- **404** — 

## OpenAPI Definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "ModelVerse Chanjing TTS API",
    "description": "Chanjing text-to-speech API, supporting standard TTS, dialect synthesis, and accent conversion.\n\n**Three Synthesis Modes:**\n\n1. **Standard TTS** (default)\n   - Use system voices or custom voices for speech synthesis\n   - Parameters: `voice_id` + `text`\n\n2. **Dialect Synthesis** (`dialect` parameter)\n   - Use cicada1.0 custom voices for dialect synthesis\n   - Parameters: `voice_id` (C-Audio-xxx) + `text` + `dialect`\n   - Supports 12 dialects\n\n3. **Accent Conversion** (`prompt_audio` parameter)\n   - Use reference audio for accent conversion\n   - Parameters: `voice_id` + `text` + `prompt_audio` + `mss`\n\n\n**Dialect Types (dialect):**\n| Value | Dialect |\n|-------|---------|\n| 0 | Other (default) |\n| 1 | Northeastern Mandarin |\n| 2 | Guanzhong Dialect |\n| 3 | Jianghuai Mandarin |\n| 5 | Jilu Mandarin |\n| 6 | Qinghai Dialect |\n| 7 | Wu Dialect |\n| 8 | Tianjin Dialect |\n| 9 | Southwestern Mandarin |\n| 10 | Central Plains Mandarin |\n| 11 | Cantonese |\n| 12 | Southern Min |\n\n**Accent Voice ID List:**\n| Voice Name | Model | Accent ID |\n|------------|-------|-----------|\n| Sichuan Male Young | cicada3.0-turbo | 89843d52ccd04e2d854decd28d6143ce |\n| Nanjing Male Young | cicada3.0-turbo | b9705cff084c4416b02f01d797025c25 |\n| Shaanxi Male Young | cicada3.0-turbo | f28c22c6d26f48f29ee4cc1380adff24 |\n| Tianjin Male Young | cicada3.0-turbo | 2c9f4ce01f254b5e9408e5af3b464900 |\n| Tianjin Female Elderly | cicada3.0-turbo | eb370cde929049d9b36debcb6161f053 |\n| Northeast Male Young | cicada3.0-turbo | 4027dfc73c6e4235911dba293f53e62f |\n| Taiwan Accent Male | cicada3.0-turbo | 63dd6a2bf2c54cbe828154f393e5d833 |\n| Southern Min Female | cicada3.0-turbo | 1880b61fc567431aafe35266057a6585 |\n| Beijing Male Young | cicada3.0-turbo | 8a18396b48b54d5f8d4143369145d357 |\n| Northeast Female Elderly | cicada3.0-turbo | ed5eea52f94045198e9ec7c45e54fb96 |\n| Henan Female Elderly | cicada3.0-turbo | 737b5b61343640139f539767c03be495 |\n| Sichuan Female Young | cicada3.0-turbo | 74afc28ab43544669f50773449acf2b5 |\n\n**Workflow:**\n1. Prepare voice:\n   - Standard synthesis: Use system voice or custom voice\n   - Dialect synthesis: Use cicada1.0 custom voice\n   - Accent conversion: Upload reference audio file to get file_id\n2. Submit TTS task → Get `task_id`\n3. Poll task status → Get audio URL\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API Server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "summary": "Submit TTS Task",
        "description": "Submit text-to-speech synthesis task, supports standard synthesis, dialect synthesis, and accent conversion.\n\n**Mode Instructions:**\n- **Standard Synthesis**: `voice_id` + `text`\n- **Dialect Synthesis**: `voice_id` (C-Audio-xxx) + `text` + `dialect`\n- **Accent Conversion**: `voice_id` + `text` + `prompt_audio` + `mss`\n",
        "operationId": "submitChanjingTtsTask",
        "tags": [
          "Chanjing TTS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitTtsRequest"
              },
              "examples": {
                "standardTts": {
                  "summary": "Standard TTS",
                  "value": {
                    "model": "cicada-tts",
                    "input": {
                      "text": "Hello, this is a TTS test"
                    },
                    "parameters": {
                      "voice_id": "f9248f3b1b42447fb9282829321cfcf2",
                      "speed": 1,
                      "pitch": 1
                    }
                  }
                },
                "dialectTts": {
                  "summary": "Dialect Synthesis",
                  "value": {
                    "model": "cicada-tts",
                    "input": {
                      "text": "Hello, this is a dialect synthesis test"
                    },
                    "parameters": {
                      "voice_id": "C-Audio-xxx",
                      "speed": 1,
                      "pitch": 1,
                      "dialect": 1
                    }
                  }
                },
                "accentTts": {
                  "summary": "Accent Conversion",
                  "value": {
                    "model": "cicada-tts",
                    "input": {
                      "text": "Hello, this is an accent conversion test"
                    },
                    "parameters": {
                      "voice_id": "f9248f3b1b42447fb9282829321cfcf2",
                      "speed": 1,
                      "pitch": 1,
                      "prompt_audio": "09eacb8ead0a423e9dcd75065ae32d25",
                      "mss": 10
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully",
            "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": "Get TTS Task Status",
        "description": "Query the execution status and result of a TTS task.\n\n**Task Status:**\n- `Pending` - Task in progress\n- `Success` - Task completed successfully\n- `Failure` - Task failed\n",
        "operationId": "getChanjingTtsTaskStatus",
        "tags": [
          "Chanjing TTS"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Task ID",
            "schema": {
              "type": "string"
            },
            "example": "task_tts_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "In Progress",
                    "value": {
                      "output": {
                        "task_id": "task_tts_abc123",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "success": {
                    "summary": "Success",
                    "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": "Failed",
                    "value": {
                      "output": {
                        "task_id": "task_tts_abc123",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067250,
                        "error_message": "TTS failed"
                      },
                      "request_id": "req_xxx"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/chanjing/list_common_audio": {
      "get": {
        "summary": "List Common Voices",
        "description": "Get system-provided common voice list",
        "operationId": "listChanjingCommonAudioForTts",
        "tags": [
          "Chanjing TTS"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, default 1",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Items per page, default 10",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Voice list retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonAudioListResponse"
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "f9248f3b1b42447fb9282829321cfcf2",
                      "name": "Sales Assistant Xiaoyun",
                      "gender": "female",
                      "lang": "multilingual"
                    },
                    {
                      "id": "a1b2c3d4e5f678901234567890123456",
                      "name": "News Anchor",
                      "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 authentication, format: Bearer {api_key}"
      }
    },
    "schemas": {
      "TtsInput": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Text content to synthesize, max 4000 characters",
            "maxLength": 4000
          }
        }
      },
      "TtsParameters": {
        "type": "object",
        "required": [
          "voice_id"
        ],
        "properties": {
          "voice_id": {
            "type": "string",
            "description": "Voice ID:\n- System voice: from common voice list\n- Custom voice: C-Audio-xxx format\n"
          },
          "speed": {
            "type": "number",
            "format": "float",
            "description": "Speech rate, range 0.5-2.0",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "description": "Pitch, range 0.5-2.0",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2
          },
          "dialect": {
            "type": "integer",
            "description": "Dialect type (for dialect synthesis):\n- 0: Other (default)\n- 1: Northeastern Mandarin\n- 2: Guanzhong Dialect\n- 3: Jianghuai Mandarin\n- 5: Jilu Mandarin\n- 6: Qinghai Dialect\n- 7: Wu Dialect\n- 8: Tianjin Dialect\n- 9: Southwestern Mandarin\n- 10: Central Plains Mandarin\n- 11: Cantonese\n- 12: Southern Min\n",
            "minimum": 0,
            "maximum": 12
          },
          "prompt_audio": {
            "type": "string",
            "description": "Voice prompt file ID (required for accent conversion)"
          },
          "mss": {
            "type": "integer",
            "description": "AI sentence segmentation word count, must be greater than 0 (required for accent conversion)",
            "minimum": 1
          },
          "callback_url": {
            "type": "string",
            "description": "Callback URL"
          }
        }
      },
      "SubmitTtsRequest": {
        "type": "object",
        "required": [
          "model",
          "input",
          "parameters"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name",
            "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": "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)"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Result audio URL list"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (returned when failed)"
          }
        }
      },
      "TaskUsage": {
        "type": "object",
        "properties": {
          "audio_duration": {
            "type": "integer",
            "description": "Audio duration in seconds"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "$ref": "#/components/schemas/TaskStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/TaskUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Request ID"
          }
        }
      },
      "CommonAudioItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Voice ID"
          },
          "name": {
            "type": "string",
            "description": "Voice name"
          },
          "gender": {
            "type": "string",
            "description": "Gender",
            "enum": [
              "male",
              "female"
            ]
          },
          "lang": {
            "type": "string",
            "description": "Language"
          }
        }
      },
      "CommonAudioListResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "description": "Object type"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommonAudioItem"
            },
            "description": "Voice list"
          },
          "total": {
            "type": "integer",
            "description": "Total count"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "size": {
            "type": "integer",
            "description": "Items per page"
          }
        }
      },
      "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": {
              "missingVoiceId": {
                "summary": "Missing voice_id",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "voice_id is required"
                  }
                }
              },
              "missingText": {
                "summary": "Missing text",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "text is required"
                  }
                }
              },
              "invalidDialect": {
                "summary": "Invalid dialect type",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "dialect must be between 0 and 12"
                  }
                }
              },
              "textTooLong": {
                "summary": "Text too long",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "text exceeds maximum length of 4000 characters"
                  }
                }
              },
              "missingMss": {
                "summary": "Accent conversion missing mss",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "mss is required for accent TTS and must be greater than 0"
                  }
                }
              }
            }
          }
        }
      },
      "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": "task not found"
              }
            }
          }
        }
      }
    }
  }
}
```