TTS外部服务接口规范

概述

本文档定义了TTS外部服务需要实现的接口规范。当您开发一个TTS服务并希望接入本系统时，您的服务需要遵循以下接口定义。

---

接口要求

基本要求

• 支持HTTP/HTTPS协议
• 返回音频流数据（支持流式传输）

请求方式

系统会根据配置向您的服务发送HTTP请求：

• 请求方法: POST
• 请求URL: {host}/{path} （host和path可配置）
• 超时时间: 默认120秒（可配置）

---

请求参数

请求参数格式

POST请求

参数通过JSON Body传递， 为方便展示，JSON字符串转为对象，具体类型以下面表格为主

{
  "text": "最近航里下达了新的规定，要求我们进一步提升客户的服务体验。",
  "original_text": "最近行里下达了新的规定，要求我们进一步提升客户的服务体验。",
  "text_lang": "zh",
  "text_emotion": "激动",
  "instruction": "用激动的语气说",
  "audio_marks": [
    {
      "id": "9c8d6fa6-f68e-4c54-b9f0-bf8c2b057784",
      "type": "phonetic",
      "isRange": true,
      "isBind": true,
      "start": 2,
      "end": 2,
      "value": "hang2",
      "label": "háng",
      "remark": "航"
    }
  ],
  "scene_style": [
    "对话",
    "浑厚低音",
    "情感微弱"
  ],
  "character_profile": [
    "配角",
    "冷漠权威",
    "大叔音"
  ]
}

---

标准请求参数说明

重要说明：本系统采用动态表单插件机制，大部分参数字段通过插件配置动态生成。以下表格列出了系统可能发送的所有标准参数，实际接收的参数取决于插件的具体配置。请根据您接入的插件类型查看对应的参数配置。

动态表单插件机制

本系统支持动态表单插件，允许通过配置定义不同的参数字段。这意味着：

1. 插件配置字段：标记为"插件配置"的字段由插件动态定义，不同插件可能有不同的字段组合
2. 系统固定字段：标记为"系统传入"是系统固定传递的
3. 字段查看方式：具体插件支持的字段请查看插件配置页面

一级参数总览

参数名	类型	必填	来源	说明
text	string	✅	系统传入	要转换为语音的文本内容(多音字处理后的文本)
original_text	string	✅	系统传入	原始文本内容（多音字处理前的文本内容）
text_lang	string	✅	系统传入	文本语言
text_emotion	string	❌	系统传入	文本情感
instruction	string	❌	系统传入	指令文本
model_properties	string	❌	系统传入	模型属性配置(是否支持指令，多音字类型等)(JSON对象转字符串)
audio_marks	string	❌	系统传入	音频标记JSON数组(详见下文)(JSON数组转字符串)
scene_style	string	❌	系统传入	文本标签JSON数组(JSON数组转字符串)
character_profile	string	❌	系统传入	发音人标签JSON数组(JSON数组转字符串)
prompt_audio(插件数据)	string或file(本地路径，远程文件)	❌	插件配置	参考音频(具体信息查看插件配置)
prompt_audio_text(插件数据)	string	❌	插件配置	参考音频文本(具体信息查看插件配置)
其他插件数据	---	---	插件配置	插件数据(具体信息查看插件配置)

audio_marks 数据结构

AudioMark 字段说明：

字段名	类型	说明
id	string	唯一标识
type	string	标记类型: text, phonetic, speed, pitch, volume, linking, emphasis, break, interval
is_range	boolean	是否为范围标记
is_bind	boolean	是否绑定
start	integer	开始位置（字符索引）
end	integer	结束位置（字符索引）
value	string/number	标记值
label	string	显示标签

---

接口实现示例

Python FastAPI 示例

import json
from typing import Optional, Union

from fastapi import FastAPI, HTTPException, UploadFile
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field

app = FastAPI()


class TTSRequest(BaseModel):
    text: str
    original_text: str
    text_lang: str
    text_emotion: Optional[str] = None
    instruction: Optional[str] = None
    model_properties: Optional[str] = None
    audio_marks: Optional[str] = None
    scene_style: Optional[str] = None
    character_profile: Optional[str] = None
    prompt_audio: Optional[Union[str, UploadFile]] = None
    prompt_audio_text: Optional[str] = None

    # 其他插件中配置的字段


@app.post("/tts")
async def text_to_speech(request: TTSRequest):
    """
    TTS接口示例
    """
    if not request.text:
        raise HTTPException(status_code=400, detail="text parameter is required")

    if request.audio_marks:
        # arr
        audio_marks = json.loads(request.audio_marks)

    if request.scene_style:
        # arr
        scene_style = json.loads(request.scene_style)

    if request.character_profile:
        # arr
        character_profile = json.loads(request.character_profile)

    # 生成音频数据（这里需要替换为实际的TTS逻辑）
    audio_data = await generate_audio()

    # 返回音频流
    return StreamingResponse(
        iter([audio_data]),
        media_type="audio/mpeg",
        headers={
            "Content-Disposition": 'attachment; filename="output.mp3"'
        }
    )


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)