# Query MOSS Voice List

> Audio Generation

Queries the list of system voices available on the MOSS platform.

This endpoint is **model-agnostic** and always routes through the MOSS channel to return upstream voice data. All query parameters are passed through to the upstream as-is.

The voice IDs can be used as the `voice` parameter in `POST /v1/audio/speech`.

## Endpoint

`GET https://api.modelverse.cn/v1/moss/audio-voices`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| limit | query | integer | No | Number of results to return; default is 20, maximum is 150. |
| offset | query | integer | No | Offset for pagination. |
| after | query | string | No | Pagination cursor; use the `next_cursor` returned from the previous page. |
| status | query | string | No | Filter by voice status; available values are determined by the server. |

## Responses

- **200** — Query successful; returns the voice list.
- **401** — Authentication failed.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "MOSS TTS 1.5 Flash Speech Synthesis",
    "version": "1.0.0",
    "description": "This is the speech synthesis API documentation for `moss-tts-1.5-flash` on ModelVerse.\n\nThe endpoints are `POST /v1/audio/speech` (synchronous) and `POST /v1/tasks/submit` (asynchronous).\n\n## Model Features\n\n- Supports high-quality speech synthesis for 30+ languages including Chinese, Cantonese, English, and more.\n- Supports both non-streaming (returns an audio URL) and SSE streaming (returns audio chunks).\n- Supports AIGC provenance metadata injection to meet compliance requirements.\n- Supports specifying an expected audio duration to control synthesis pacing.\n\n## Billing\n\n`moss-tts-1.5-flash` is billed by **input character count**, with usage reflected in `usage.input_characters` in the response.\n\n## Usage Notes\n\n- The `voice` (voice ID) must belong to the supported voice list for `moss-tts-1.5-flash`; you can query this on the MOSS official platform.\n- `language` must be the **full English name** of a supported language (e.g., `Chinese`, `English`); language codes such as `zh` or `en` are not supported. When omitted, the model automatically detects the language.\n- For streaming requests (`stream=true`), `response_format` is forced to `pcm`, and `stream_format` is fixed to `sse`; any values passed by the user will be ignored.\n- For non-streaming requests, `delivery_method` is fixed to `url` and cannot be modified by the user.\n- `aigc_metadata` is an optional AIGC provenance metadata object in JSON format.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "Mainland China"
    },
    {
      "url": "https://api.umodelverse.ai",
      "description": "Global"
    },
    {
      "url": "https://api-us-ca.umodelverse.ai",
      "description": "Los Angeles, US"
    },
    {
      "url": "https://api-sg.umodelverse.ai",
      "description": "Singapore"
    },
    {
      "url": "https://api-ge-fra.umodelverse.ai",
      "description": "Frankfurt"
    }
  ],
  "tags": [
    {
      "name": "MOSS TTS",
      "description": "Speech synthesis interface for `moss-tts-1.5-flash`."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/speech": {
      "post": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "createMossTTS15FlashSpeech",
        "summary": "MOSS TTS 1.5 Flash Speech Synthesis (Synchronous)",
        "description": "Converts text to speech. By default, returns a JSON containing an audio URL in non-streaming mode; when `stream=true`, returns an SSE stream of audio data.\n\n`input` and `voice` are required; all other fields are optional.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MossTTSSpeechRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic synthesis (MP3)",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": "Hello, welcome to the Mosi intelligent speech synthesis service.",
                    "voice": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                    "response_format": "mp3"
                  }
                },
                "withOptions": {
                  "summary": "With language, duration, and AIGC metadata",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": "Hello, welcome to the Mosi intelligent speech synthesis service.",
                    "voice": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                    "response_format": "mp3",
                    "language": "Chinese",
                    "expected_duration_sec": 5.5,
                    "aigc_metadata": {
                      "content_producer": "ucloud",
                      "produce_id": "12345"
                    }
                  }
                },
                "stream": {
                  "summary": "SSE streaming synthesis",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": "Hello, welcome to Mosi Intelligence.",
                    "voice": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                    "stream": true,
                    "language": "Chinese"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synthesis successful. Returns JSON in non-streaming mode (audio URL and usage); returns `text/event-stream` in streaming mode.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSSpeechResponse"
                },
                "examples": {
                  "urlMode": {
                    "summary": "Non-streaming synthesis result",
                    "value": {
                      "usage": {
                        "input_characters": 22,
                        "prompt_tokens": 310,
                        "completion_tokens": 64,
                        "total_tokens": 374
                      },
                      "id": "84a364c0-8709-4174-ae76-fabaabd7dc69",
                      "object": "audio.speech",
                      "status": "SUCCESS",
                      "url": "https://img.mosi.cn/matrix/transcoded/xxx/xxx.mp3?Expires=1795141451&...",
                      "response_format": "mp3",
                      "content_type": "audio/mpeg",
                      "created_at": 1794901447
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE event stream. Each event consists of `event:` and `data:<JSON>`.\n\nAudio data is returned in Base64-encoded chunks; concatenating them in order reconstructs the full audio.\nThe termination event carries the final usage information.\n"
                },
                "examples": {
                  "streamEvents": {
                    "summary": "Streaming event example (excerpt)",
                    "value": "event: speech.audio.chunk\ndata: {\"audio\": \"base64encodedaudiodata...\"}\n\nevent: speech.audio.done\ndata: {\"usage\": {\"input_characters\": 22, \"prompt_tokens\": 310, \"completion_tokens\": 64, \"total_tokens\": 374}}\n"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters, such as missing required fields, non-existent voice_id, empty input, unsupported language code, etc.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed; API Key is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Request rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Upstream service internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "submitMossTTS15FlashAsyncTask",
        "summary": "MOSS TTS 1.5 Flash Async Task Submission",
        "description": "Submits an asynchronous speech synthesis task. The interface returns a `task_id`, which can be used with `GET /v1/tasks/status` to query task status and results.\n\nAsync tasks are fixed to use `delivery_method=url`, `stream=false`, and `async=true`; the user does not need to pass these.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MossTTSAsyncTaskRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic async task",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": {
                      "text": "Hello, welcome to the Mosi intelligent speech synthesis service."
                    },
                    "parameters": {
                      "voice_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                      "response_format": "mp3"
                    }
                  }
                },
                "withOptions": {
                  "summary": "With language, duration, and callback",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": {
                      "text": "Hello, welcome to the Mosi intelligent speech synthesis service."
                    },
                    "parameters": {
                      "voice_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                      "response_format": "mp3",
                      "language": "Chinese",
                      "expected_duration_sec": 5.5,
                      "webhook_url": "https://example.com/webhook",
                      "aigc_metadata": {
                        "content_producer": "ucloud",
                        "produce_id": "12345"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully; returns the task ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSAsyncTaskResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "Task submitted",
                    "value": {
                      "output": {
                        "task_id": "task-xxx"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "getMossTTS15FlashTaskStatus",
        "summary": "Query MOSS TTS 1.5 Flash Async Task Status",
        "description": "Queries the execution status and result of an asynchronous speech synthesis task.\n\n**Task Statuses:**\n- `Pending` / `Processing` — Task in progress\n- `Success` — Task completed successfully\n- `Failure` — Task failed\n\n**On Success:**\n- `output.task_status`: `Success`\n- `output.urls`: Array of audio download URLs\n- `usage`: Usage information (e.g., `input_characters`)\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Async task ID",
            "schema": {
              "type": "string"
            },
            "example": "task-xxx"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status query successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "output": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "string",
                          "description": "Task ID"
                        },
                        "task_status": {
                          "type": "string",
                          "description": "Task status"
                        },
                        "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": "Array of audio download URLs (returned only on success)"
                        },
                        "error_message": {
                          "type": "string",
                          "description": "Error message (returned only on failure)"
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "input_characters": {
                          "type": "integer",
                          "description": "Input character count"
                        },
                        "prompt_tokens": {
                          "type": "integer"
                        },
                        "completion_tokens": {
                          "type": "integer"
                        },
                        "total_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Task succeeded",
                    "value": {
                      "output": {
                        "task_id": "task-xxx",
                        "task_status": "Success",
                        "submit_time": 1704067200,
                        "finish_time": 1704067250,
                        "urls": [
                          "https://example.com/audio.mp3"
                        ]
                      },
                      "usage": {
                        "input_characters": 22,
                        "prompt_tokens": 310,
                        "completion_tokens": 64,
                        "total_tokens": 374
                      }
                    }
                  },
                  "pending": {
                    "summary": "Task in progress",
                    "value": {
                      "output": {
                        "task_id": "task-xxx",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      }
                    }
                  },
                  "failure": {
                    "summary": "Task failed",
                    "value": {
                      "output": {
                        "task_id": "task-xxx",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067250,
                        "error_message": "Speech synthesis failed"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/moss/audio-voices": {
      "get": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "listMossTTSVoices",
        "summary": "Query MOSS Voice List",
        "description": "Queries the list of system voices available on the MOSS platform.\n\nThis endpoint is **model-agnostic** and always routes through the MOSS channel to return upstream voice data. All query parameters are passed through to the upstream as-is.\n\nThe voice IDs can be used as the `voice` parameter in `POST /v1/audio/speech`.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "Number of results to return; default is 20, maximum is 150."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Offset for pagination."
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor; use the `next_cursor` returned from the previous page."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by voice status; available values are determined by the server."
          }
        ],
        "responses": {
          "200": {
            "description": "Query successful; returns the voice list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSVoicesResponse"
                },
                "examples": {
                  "voices": {
                    "summary": "Voice list example",
                    "value": {
                      "object": "list",
                      "data": [
                        {
                          "id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                          "object": "audio.voice",
                          "name": "Zhou Zhou",
                          "created_at": 1710000000
                        }
                      ],
                      "first_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                      "last_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                      "has_more": true,
                      "next_cursor": "b2Zmc2V0OjIw"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Authenticate using Bearer Token, in the format `Authorization: Bearer <API Key>`."
      }
    },
    "schemas": {
      "MossTTSSpeechRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input",
          "voice"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "moss-tts-1.5-flash",
            "description": "Model name, always `moss-tts-1.5-flash`."
          },
          "input": {
            "type": "string",
            "description": "Text to synthesize, required."
          },
          "voice": {
            "type": "string",
            "description": "Voice ID, required. Must belong to the supported voice list for `moss-tts-1.5-flash` and cannot be mixed with other models.\n"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "mp3",
              "wav",
              "pcm",
              "flac",
              "aac",
              "opus"
            ],
            "default": "mp3",
            "description": "Output audio format. Default is `mp3` for non-streaming; **forced to `pcm`** for streaming requests (`stream=true`), and any user-provided value will be ignored.\n"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Whether to enable SSE streaming output. When `true`, returns an SSE event stream with audio data chunks.\n**In streaming mode, `response_format` is forced to `pcm`, and `stream_format` is fixed to `sse`.**\n"
          },
          "language": {
            "type": "string",
            "description": "The pronunciation language of the target text; does not translate the text. Must be the **full English name** of a supported language, such as `Chinese` or `English`; language codes like `zh` or `en` are not supported. When omitted, the model automatically detects the language.\n",
            "enum": [
              "Chinese",
              "Cantonese",
              "English",
              "Arabic",
              "Czech",
              "Danish",
              "Dutch",
              "Finnish",
              "French",
              "German",
              "Greek",
              "Hebrew",
              "Hindi",
              "Hungarian",
              "Italian",
              "Japanese",
              "Korean",
              "Macedonian",
              "Malay",
              "Persian",
              "Polish",
              "Portuguese",
              "Romanian",
              "Russian",
              "Spanish",
              "Swahili",
              "Swedish",
              "Tagalog",
              "Thai",
              "Turkish",
              "Vietnamese"
            ]
          },
          "expected_duration_sec": {
            "type": "number",
            "description": "Expected duration of the generated audio in seconds."
          },
          "aigc_metadata": {
            "type": "object",
            "description": "AIGC provenance metadata, JSON object format."
          }
        }
      },
      "MossTTSSpeechResponse": {
        "type": "object",
        "description": "Non-streaming speech synthesis success response.",
        "required": [
          "id",
          "object",
          "status",
          "url",
          "response_format",
          "content_type",
          "created_at"
        ],
        "properties": {
          "usage": {
            "type": "object",
            "properties": {
              "input_characters": {
                "type": "integer",
                "description": "Input character count, the billing basis."
              },
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          },
          "id": {
            "type": "string",
            "description": "Unique request identifier."
          },
          "object": {
            "type": "string",
            "const": "audio.speech"
          },
          "status": {
            "type": "string",
            "const": "SUCCESS"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Download URL of the synthesized audio."
          },
          "response_format": {
            "type": "string",
            "description": "The actual audio format returned."
          },
          "content_type": {
            "type": "string",
            "description": "Audio MIME type, e.g., `audio/mpeg`."
          },
          "created_at": {
            "type": "integer",
            "description": "Creation time, Unix timestamp in seconds."
          }
        }
      },
      "MossTTSAsyncTaskRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "moss-tts-1.5-flash",
            "description": "Model name, always `moss-tts-1.5-flash`."
          },
          "input": {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "description": "Text to synthesize, required."
              }
            }
          },
          "parameters": {
            "type": "object",
            "properties": {
              "voice_id": {
                "type": "string",
                "description": "Voice ID, required."
              },
              "response_format": {
                "type": "string",
                "enum": [
                  "mp3",
                  "wav",
                  "pcm",
                  "flac",
                  "aac",
                  "opus"
                ],
                "default": "mp3",
                "description": "Output audio format; default is `mp3`."
              },
              "language": {
                "type": "string",
                "description": "The pronunciation language; must be the full English name, such as `Chinese` or `English`; language codes like `zh` or `en` are not supported.\n",
                "enum": [
                  "Chinese",
                  "Cantonese",
                  "English",
                  "Arabic",
                  "Czech",
                  "Danish",
                  "Dutch",
                  "Finnish",
                  "French",
                  "German",
                  "Greek",
                  "Hebrew",
                  "Hindi",
                  "Hungarian",
                  "Italian",
                  "Japanese",
                  "Korean",
                  "Macedonian",
                  "Malay",
                  "Persian",
                  "Polish",
                  "Portuguese",
                  "Romanian",
                  "Russian",
                  "Spanish",
                  "Swahili",
                  "Swedish",
                  "Tagalog",
                  "Thai",
                  "Turkish",
                  "Vietnamese"
                ]
              },
              "expected_duration_sec": {
                "type": "number",
                "description": "Expected duration of the generated audio in seconds."
              },
              "webhook_url": {
                "type": "string",
                "format": "uri",
                "description": "HTTPS URL to callback when the async task completes."
              },
              "aigc_metadata": {
                "type": "object",
                "description": "AIGC provenance metadata, JSON object format."
              }
            }
          }
        }
      },
      "MossTTSAsyncTaskResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Async task ID."
              }
            },
            "description": "Unique request identifier."
          }
        }
      },
      "MossTTSErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "Error description."
              },
              "type": {
                "type": "string"
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "code": {
                "type": "string"
              },
              "trace_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "MossTTSVoicesResponse": {
        "type": "object",
        "description": "MOSS voice list response.",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list",
            "description": "Always `list`."
          },
          "data": {
            "type": "array",
            "description": "Voice list; empty array when no voices are available.",
            "items": {
              "$ref": "#/components/schemas/MossTTSVoiceItem"
            }
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether there are more voices."
          },
          "first_id": {
            "type": "string",
            "description": "The first voice id on the current page, returned when `data` is non-empty."
          },
          "last_id": {
            "type": "string",
            "description": "The last voice id on the current page, returned when `data` is non-empty."
          },
          "next_cursor": {
            "type": "string",
            "description": "Cursor for the next page, returned when there is a next page; can be passed as `after` in the next request."
          }
        }
      },
      "MossTTSVoiceItem": {
        "type": "object",
        "required": [
          "id",
          "object",
          "name",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Voice ID; referenced by the TTS interface."
          },
          "object": {
            "type": "string",
            "const": "audio.voice",
            "description": "Always `audio.voice`."
          },
          "name": {
            "type": "string",
            "description": "Human-readable name; may be an empty string."
          },
          "created_at": {
            "type": "integer",
            "description": "Creation time, Unix timestamp in seconds."
          }
        }
      }
    }
  }
}
```
