TTS外部服务接口规范

概述

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

---

接口要求

基本要求

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

请求方式

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

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

---

请求参数

请求参数格式

POST请求

参数通过JSON Body传递：

{
  "text": "最近航里下达了新的规定，要求我们进一步提升客户的服务体验。",
  "original_text": "最近行里下达了新的规定，要求我们进一步提升客户的服务体验。",
  "text_lang": "zh",
  "text_emotion": "激动",
  "instruction": "用激动的语气说",
  "audioMarks": [
    {
      "id": "9c8d6fa6-f68e-4c54-b9f0-bf8c2b057784",
      "type": "phonetic",
      "isRange": true,
      "isBind": true,
      "start": 2,
      "end": 2,
      "value": "hang2",
      "label": "háng",
      "remark": "航"
    }
  ]
}

---

标准请求参数说明

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

动态表单插件机制

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

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

一级参数总览

参数名	类型	必填	来源	说明
text	string	✅	系统传入	要转换为语音的文本内容(多音字处理后的文本)
original_text	string	✅	系统传入	原始文本内容（多音字处理前的文本内容）
text_lang	string	✅	系统传入	文本语言
text_emotion	string	❌	系统传入	文本情感
instruction	string	❌	系统传入	指令文本
model_properties	json对象	❌	系统传入	模型属性配置(是否支持指令，多音字类型等)
audio_marks	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 示例

from fastapi import FastAPI, HTTPException, UploadFile
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Any, Union
import json

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[Dict[str, Any]] = None
    audio_marks: Optional[List[Dict[str, Any]]] = 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")
    
    # 生成音频数据（这里需要替换为实际的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)