# 通过 RESTful API 接入自定义 TTS (/zh-CN/ai/build/custom-model-integration/custom-tts) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 功能简介 [#功能简介] 通过接入自定义文本转语音 (TTS) 服务,你可以将自研 TTS、私有化部署 TTS 或第三方 TTS 服务作为对话式智能体的语音合成模块。本文介绍如何准备兼容 OpenAI TTS 协议的 HTTP 服务,并在创建对话式智能体时通过 `generic_http` TTS 配置接入该服务。 ## 实现原理 [#实现原理] 声网对话式 AI 引擎通过扩展的 OpenAI TTS 协议调用你的 TTS 服务。调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)接口时,将 `tts.vendor` 设置为 `generic_http` 并配置 TTS 服务地址后,智能体会在需要播报文本时向该地址发起 HTTP 请求。 ## 前提条件 [#前提条件] 开始前,请确保你已经: - 参考[实现对话式智能体](/zh-CN/ai/get-started/quick-start)实现了与 AI 智能体对话互动的基本逻辑。 - 准备好可被声网对话式 AI 引擎访问的 TTS HTTP 服务。 - 确保 TTS 服务支持 HTTP/1.1 或更高版本,生产环境建议使用 HTTPS。 - 确保 TTS 服务能够返回 PCM 格式音频数据。 ## 实现步骤 [#实现步骤] ### 1. 准备 TTS 服务接口 [#1-准备-tts-服务接口] 你的 TTS 服务需要提供一个兼容 OpenAI TTS 协议的 HTTP 接口。基础要求如下: - 请求方法:`POST` - 请求路径:`/audio/speech` - 请求 Header:支持通过 `Authorization: Bearer ` 鉴权 - 请求 Body:JSON 格式 - 响应 Body:PCM 音频数据流 请求体示例如下: ```json { "model": "your-tts-model", "input": "欢迎使用声网对话式 AI 引擎。", "voice": "alloy", "speed": 1.0, "sample_rate": 16000, "response_format": "pcm", "instruction": "calm" } ``` 请求体字段说明如下: | 字段 | 类型 | 说明 | | --- | --- | --- | | `input` | String | 待合成的文本内容。由声网对话式 AI 引擎根据智能体回复自动传入。 | | `model` | String | TTS 模型名称。如果你的 TTS 服务不区分模型,可以忽略该字段。 | | `voice` | String | 音色名称。如果你的 TTS 服务不区分音色,可以忽略该字段。 | | `speed` | Number | 语速。 | | `sample_rate` | Integer | 输出音频采样率,单位为 Hz,默认值为 `16000`。 | | `response_format` | String | 输出音频格式,默认值为 `pcm`。当前仅支持 `pcm`。 | | `instruction` | String | 语音风格、情绪或其他播报指令。 | :::warning[注意] 如果你的 TTS 服务不支持多采样率,请确保实际返回音频的采样率与创建智能体时配置的 `tts.params.sample_rate` 一致。 ::: ### 2. 验证 TTS 服务响应 [#2-验证-tts-服务响应] 你可以先使用 curl 验证 TTS 服务是否能正常返回 PCM 音频流: ```bash curl --request POST \ --url https://your-tts-service.example.com/v1/audio/speech \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "your-tts-model", "input": "欢迎使用声网对话式 AI 引擎。", "voice": "alloy", "speed": 1.0, "sample_rate": 16000, "response_format": "pcm" }' \ --output test.pcm ``` 服务成功处理请求后,应以 HTTP 分块传输编码(Chunked Transfer Encoding)的方式流式返回合成后的 PCM 音频数据。 如果请求失败,建议返回标准 HTTP 错误状态码,并在响应体中携带 JSON 格式错误信息。例如: ```json { "error": { "message": "Incorrect API key provided.", "type": "invalid_request_error", "param": null, "code": "invalid_api_key" } } ``` ### 3. 配置智能体使用自定义 TTS [#3-配置智能体使用自定义-tts] 调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)接口时,在 `tts` 模块中将 `vendor` 设置为 `generic_http`,并配置你的 TTS 服务地址和参数。以下仅展示 `properties.tts` 配置: ```json { "tts": { "vendor": "generic_http", "url": "https://your-tts-service.example.com/v1/audio/speech", "headers": { "Authorization": "Bearer " }, "params": { "model": "your-tts-model", "voice": "alloy", "speed": 1.0, "sample_rate": 16000, "response_format": "pcm", "instruction": "calm", "enable_request_id": false } } } ``` `generic_http` 相关配置说明如下: | 配置路径 | 类型 | 是否必需 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | `tts.vendor` | String | 是 | - | 设置为 `generic_http`,表示使用自定义 TTS 服务。 | | `tts.url` | String | 是 | - | TTS 服务地址,要求兼容 OpenAI TTS 协议。 | | `tts.headers` | Object | 否 | - | 调用 TTS 服务时携带的请求头,常用于配置 `Authorization`。 | | `tts.params` | Object | 否 | - | TTS 请求参数。除本文列出的字段外,还支持按需配置其他字段,系统会将其透传给 TTS 服务。 | | `tts.params.api_key` | String | 否 | - | TTS 服务鉴权 API key。如果配置该字段,系统会在调用 TTS 服务时自动携带 `Authorization: Bearer `。 | | `tts.params.model` | String | 否 | - | TTS 模型名称。 | | `tts.params.voice` | String | 否 | - | 音色名称。如果你的 TTS 服务暂不支持多音色,可以忽略该参数。 | | `tts.params.speed` | Number | 否 | - | 语速。 | | `tts.params.sample_rate` | Integer | 否 | `16000` | 输出音频采样率,单位为 Hz。如果你的 TTS 服务暂不支持多采样率,请确保返回音频的采样率与该配置一致。 | | `tts.params.response_format` | String | 否 | `pcm` | 输出音频格式。当前仅支持 `pcm`。 | | `tts.params.instruction` | String | 否 | - | 语音风格、情绪或其他播报指令。 | | `tts.params.enable_request_id` | Boolean | 否 | `false` | 是否在 TTS 请求体中附带 `request_id`、`request_seq_id` 和 `request_end`。 | :::info[信息] `tts.headers.Authorization` 和 `tts.params.api_key` 至少配置一个。如果同时配置,系统优先使用 `tts.headers.Authorization`。 ::: ### 4. 按需接收请求标识 [#4-按需接收请求标识] 如果你的 TTS 服务需要区分同一轮播报中的多次请求,可以将 `tts.params.enable_request_id` 设置为 `true`。开启后,系统会在发送给 TTS 服务的请求体中附带以下字段: | 字段 | 类型 | 说明 | | --- | --- | --- | | `request_id` | String | 单次 TTS 请求的唯一标识。 | | `request_seq_id` | Integer | 同一轮播报内的请求序号,从 `0` 开始递增。 | | `request_end` | Boolean | 是否为同一轮播报的最后一次请求。 |