# MOSS TTS 1.5 Flash 语音合成（同步）

> 音频生成

将文本合成为语音。默认非流式返回包含音频 URL 的 JSON；当 `stream=true` 时返回 SSE 流式音频。

`input`、`voice` 为必填字段，其余为可选。

## 请求地址

`POST https://api.modelverse.cn/v1/audio/speech`

## 请求体

## 响应

- **200** — 合成成功。非流式返回 JSON（音频 URL 与用量）；流式返回 `text/event-stream`。

- **400** — 请求参数无效，例如缺少必填字段、voice_id 不存在、input 为空、language 填写了不支持的语言代码等。

- **401** — 鉴权失败，API Key 缺失或无效。
- **429** — 请求频率超限。
- **500** — 上游服务内部错误。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "MOSS TTS 1.5 Flash 语音合成",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 `moss-tts-1.5-flash` 的语音合成接口文档。\n\n接口路径为 `POST /v1/audio/speech`（同步）与 `POST /v1/tasks/submit`（异步）。\n\n## 模型特性\n\n- 支持中文、粤语、英语等 30+ 种语言的高质量语音合成。\n- 支持非流式（返回音频 URL）与 SSE 流式（逐块返回音频）两种输出方式。\n- 支持 AIGC 溯源元数据注入，满足合规要求。\n- 支持指定期望音频时长，用于控制合成节奏。\n\n## 计费口径\n\n`moss-tts-1.5-flash` 按 **输入字符数** 计费，用量体现在响应的 `usage.input_characters` 中。\n\n## 使用注意\n\n- `voice`（音色 ID）必须属于 `moss-tts-1.5-flash` 支持的音色列表，可在 MOSS 官方平台查询。\n- `language` 必须填写支持语言的 **英文全称**（如 `Chinese`、`English`），不支持 `zh`、`en` 等语言代码。省略时模型自动判断。\n- 流式请求（`stream=true`）时 `response_format` 被强制为 `pcm`，`stream_format` 固定为 `sse`；用户传入的值会被忽略。\n- 非流式请求固定使用 `delivery_method=url`，用户不可修改。\n- `aigc_metadata` 为可选的 AIGC 溯源元数据，JSON 对象格式。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "中国大陆"
    },
    {
      "url": "https://api.umodelverse.ai",
      "description": "海外"
    },
    {
      "url": "https://api-us-ca.umodelverse.ai",
      "description": "美国洛杉矶"
    },
    {
      "url": "https://api-sg.umodelverse.ai",
      "description": "新加坡"
    },
    {
      "url": "https://api-ge-fra.umodelverse.ai",
      "description": "法兰克福"
    }
  ],
  "tags": [
    {
      "name": "MOSS TTS",
      "description": "`moss-tts-1.5-flash` 的语音合成接口。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/speech": {
      "post": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "createMossTTS15FlashSpeech",
        "summary": "MOSS TTS 1.5 Flash 语音合成（同步）",
        "description": "将文本合成为语音。默认非流式返回包含音频 URL 的 JSON；当 `stream=true` 时返回 SSE 流式音频。\n\n`input`、`voice` 为必填字段，其余为可选。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MossTTSSpeechRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础合成（MP3）",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": "你好，欢迎使用模思智能语音合成服务。",
                    "voice": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                    "response_format": "mp3"
                  }
                },
                "withOptions": {
                  "summary": "带语言、时长与 AIGC 元数据",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": "你好，欢迎使用模思智能语音合成服务。",
                    "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 流式合成",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": "你好，欢迎使用模思智能。",
                    "voice": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                    "stream": true,
                    "language": "Chinese"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "合成成功。非流式返回 JSON（音频 URL 与用量）；流式返回 `text/event-stream`。\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSSpeechResponse"
                },
                "examples": {
                  "urlMode": {
                    "summary": "非流式合成结果",
                    "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:` 与 `data:<JSON>` 组成。\n\n音频数据以 Base64 编码分块返回，按事件顺序拼接后可还原完整音频。\n终止事件携带最终用量信息。\n"
                },
                "examples": {
                  "streamEvents": {
                    "summary": "流式事件示例（节选）",
                    "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": "请求参数无效，例如缺少必填字段、voice_id 不存在、input 为空、language 填写了不支持的语言代码等。\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败，API Key 缺失或无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "请求频率超限。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "上游服务内部错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "submitMossTTS15FlashAsyncTask",
        "summary": "MOSS TTS 1.5 Flash 异步任务提交",
        "description": "提交异步语音合成任务。接口返回 `task_id`，可通过 `GET /v1/tasks/status` 查询任务状态与结果。\n\n异步任务固定使用 `delivery_method=url`、`stream=false`、`async=true`，用户无需传入。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MossTTSAsyncTaskRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础异步任务",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": {
                      "text": "你好，欢迎使用模思智能语音合成服务。"
                    },
                    "parameters": {
                      "voice_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                      "response_format": "mp3"
                    }
                  }
                },
                "withOptions": {
                  "summary": "带语言、时长与回调",
                  "value": {
                    "model": "moss-tts-1.5-flash",
                    "input": {
                      "text": "你好，欢迎使用模思智能语音合成服务。"
                    },
                    "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": "任务提交成功，返回任务 ID。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSAsyncTaskResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "任务已提交",
                    "value": {
                      "output": {
                        "task_id": "task-xxx"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "getMossTTS15FlashTaskStatus",
        "summary": "查询 MOSS TTS 1.5 Flash 异步任务状态",
        "description": "查询异步语音合成任务的执行状态与结果。\n\n**任务状态：**\n- `Pending` / `Processing` — 任务进行中\n- `Success` — 任务成功完成\n- `Failure` — 任务失败\n\n**成功时返回：**\n- `output.task_status`: `Success`\n- `output.urls`: 音频下载 URL 数组\n- `usage`: 用量信息（`input_characters` 等）\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "异步任务 ID",
            "schema": {
              "type": "string"
            },
            "example": "task-xxx"
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "output": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "string",
                          "description": "任务 ID"
                        },
                        "task_status": {
                          "type": "string",
                          "description": "任务状态"
                        },
                        "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": "错误信息（仅失败时返回）"
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "input_characters": {
                          "type": "integer",
                          "description": "输入字符数"
                        },
                        "prompt_tokens": {
                          "type": "integer"
                        },
                        "completion_tokens": {
                          "type": "integer"
                        },
                        "total_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "任务成功",
                    "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": "任务进行中",
                    "value": {
                      "output": {
                        "task_id": "task-xxx",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      }
                    }
                  },
                  "failure": {
                    "summary": "任务失败",
                    "value": {
                      "output": {
                        "task_id": "task-xxx",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067250,
                        "error_message": "语音合成失败"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "任务不存在。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/moss/audio-voices": {
      "get": {
        "tags": [
          "MOSS TTS"
        ],
        "operationId": "listMossTTSVoices",
        "summary": "查询 MOSS 音色列表",
        "description": "查询 MOSS 平台可用的系统音色列表。\n\n该接口**与模型无关**，固定走 MOSS 渠道返回上游音色数据。所有 query 参数均原样透传给上游。\n\n音色 ID 可用于 `POST /v1/audio/speech` 的 `voice` 参数。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "返回数量，默认 20，最大 150。"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "偏移量。"
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "分页游标，取上一页返回的 `next_cursor`。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "按音色状态过滤；具体可用值以服务端为准。"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功，返回音色列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSVoicesResponse"
                },
                "examples": {
                  "voices": {
                    "summary": "音色列表示例",
                    "value": {
                      "object": "list",
                      "data": [
                        {
                          "id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
                          "object": "audio.voice",
                          "name": "周周",
                          "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": "鉴权失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MossTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "使用 Bearer Token 鉴权，格式为 `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": "模型名称，固定为 `moss-tts-1.5-flash`。"
          },
          "input": {
            "type": "string",
            "description": "待合成文本，必填。"
          },
          "voice": {
            "type": "string",
            "description": "音色 ID，必填。必须属于 `moss-tts-1.5-flash` 支持的音色列表，不能与其他模型混用。\n"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "mp3",
              "wav",
              "pcm",
              "flac",
              "aac",
              "opus"
            ],
            "default": "mp3",
            "description": "输出音频格式。非流式默认 `mp3`；**流式请求（`stream=true`）时强制为 `pcm`**，用户传入的值会被忽略。\n"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否开启 SSE 流式输出。`true` 时返回 SSE 事件流，逐块返回音频数据。\n**流式模式下 `response_format` 强制为 `pcm`，`stream_format` 固定为 `sse`。**\n"
          },
          "language": {
            "type": "string",
            "description": "目标文本的发音语言，不会翻译文本。必须填写支持语言的 **英文全称**，如 `Chinese`、`English`；不支持 `zh`、`en` 等语言代码。省略时模型自动判断。\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": "期望生成音频的时长（秒）。"
          },
          "aigc_metadata": {
            "type": "object",
            "description": "AIGC 溯源元数据，JSON 对象格式。"
          }
        }
      },
      "MossTTSSpeechResponse": {
        "type": "object",
        "description": "非流式语音合成成功响应。",
        "required": [
          "id",
          "object",
          "status",
          "url",
          "response_format",
          "content_type",
          "created_at"
        ],
        "properties": {
          "usage": {
            "type": "object",
            "properties": {
              "input_characters": {
                "type": "integer",
                "description": "输入字符数，计费依据。"
              },
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          },
          "id": {
            "type": "string",
            "description": "请求唯一标识。"
          },
          "object": {
            "type": "string",
            "const": "audio.speech"
          },
          "status": {
            "type": "string",
            "const": "SUCCESS"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "合成音频的下载 URL。"
          },
          "response_format": {
            "type": "string",
            "description": "实际返回的音频格式。"
          },
          "content_type": {
            "type": "string",
            "description": "音频 MIME 类型，如 `audio/mpeg`。"
          },
          "created_at": {
            "type": "integer",
            "description": "创建时间，Unix 时间戳（秒）。"
          }
        }
      },
      "MossTTSAsyncTaskRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "moss-tts-1.5-flash",
            "description": "模型名称，固定为 `moss-tts-1.5-flash`。"
          },
          "input": {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "description": "待合成文本，必填。"
              }
            }
          },
          "parameters": {
            "type": "object",
            "properties": {
              "voice_id": {
                "type": "string",
                "description": "音色 ID，必填。"
              },
              "response_format": {
                "type": "string",
                "enum": [
                  "mp3",
                  "wav",
                  "pcm",
                  "flac",
                  "aac",
                  "opus"
                ],
                "default": "mp3",
                "description": "输出音频格式，默认 `mp3`。"
              },
              "language": {
                "type": "string",
                "description": "目标文本的发音语言，必须填写英文全称，如 `Chinese`、`English`；不支持 `zh`、`en` 等语言代码。\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": "期望生成音频的时长（秒）。"
              },
              "webhook_url": {
                "type": "string",
                "format": "uri",
                "description": "异步任务完成后回调的 HTTPS URL。"
              },
              "aigc_metadata": {
                "type": "object",
                "description": "AIGC 溯源元数据，JSON 对象格式。"
              }
            }
          }
        }
      },
      "MossTTSAsyncTaskResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "异步任务 ID。"
              }
            },
            "description": "请求唯一标识。"
          }
        }
      },
      "MossTTSErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "错误描述。"
              },
              "type": {
                "type": "string"
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "code": {
                "type": "string"
              },
              "trace_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "MossTTSVoicesResponse": {
        "type": "object",
        "description": "MOSS 音色列表响应。",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list",
            "description": "固定为 `list`。"
          },
          "data": {
            "type": "array",
            "description": "音色列表；无可用音色时为空数组。",
            "items": {
              "$ref": "#/components/schemas/MossTTSVoiceItem"
            }
          },
          "has_more": {
            "type": "boolean",
            "description": "是否还有更多音色。"
          },
          "first_id": {
            "type": "string",
            "description": "`data` 非空时返回当前页首个 voice id。"
          },
          "last_id": {
            "type": "string",
            "description": "`data` 非空时返回当前页末个 voice id。"
          },
          "next_cursor": {
            "type": "string",
            "description": "有下一页时返回游标；下一次请求可作为 `after` 传入。"
          }
        }
      },
      "MossTTSVoiceItem": {
        "type": "object",
        "required": [
          "id",
          "object",
          "name",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "voice id；TTS 接口引用该值。"
          },
          "object": {
            "type": "string",
            "const": "audio.voice",
            "description": "固定为 `audio.voice`。"
          },
          "name": {
            "type": "string",
            "description": "用户可读名称；可能为空字符串。"
          },
          "created_at": {
            "type": "integer",
            "description": "创建时间，Unix 时间戳，单位为秒。"
          }
        }
      }
    }
  }
}
```
