综述

XSwitch 是一个软件交换开发框架和实现，基于 XSwitch 实现。在具备常用软交换功能的同时，提供了丰富的 API 接口与第三方对接。AI 接口是在 XSwitch 基础上开发的模块和接口，为了更好地与第三方对接。

本文档编写的目的在于给基于 XSwitch 及 AI-API 接口开发的开发人员提供一个简要的说明和参考。

本文档是 AI-API 文档。AI-API 提供双向 HTTP 相关接口，不仅限于 AI 应用，普通基于按键（DTMF）的会话控制也可以使用。

本文档主要基于 HTTP 协议，侧重于 Web 程序员，对非 Web 程序员，可以参考我们基于消息队列的XCC 接口。

支持双向 HTTP 接口，使用 JSON 消息格式封装，支持 AI 开发与对接。

通话控制需要跟踪会话状态，也就是说需要一个状态机，然后对于很多 Web 程序员来说，开发和维护一个底层的状态机是一件比较困难的事。所以，我们通过实现了双向的 HTTP 接口，让状态机对于 Web 程序员变得简单。

所谓双向 HTTP，就是说 XSwitch 即实现了 HTTP 客户端也实现了 HTTP 服务端。为了能通过 AI-API 跟 XSwitch 交互，控制侧（客户侧）的程序也需要同时支持 HTTP 服务端和客户端。

在 AI 时代，越来越多的设备和组件对智能语音提出了更多的要求。而电话是语音最佳的载体。所以，我们在 XSwitch 中实现了与主流 AI 平台的语音接口互通，旨在给第三方应用程序提供更丰富接接口。

系统使用 XSwitch 标准的 ASR 接口。识到到语音后，与外界通过事件通信。语音只在 XSwitch 中交互。

• 用户 App 发起外呼 ①
• 外呼请求到达 FreeSWITCH 后，通过 ②③ 发起呼叫
• 用户接听后启动语音识别，如mod_baidu ④⑤
• 识别结果通过mod_ai送到 HTTP 服务器 ⑦
• HTTP 服务器可以内置于用户 App 中，也可以用自己的方法通知 App

XSwitch 与外界通信有多种方式，包括但不限于：

• mod_event_socket：XSwitch 原生的通信接口
• mod_hiredis：Redis 接口
• mod_verto：Websocket 接口
• mod_ai：HTTP 接口
• mod_curl：HTTP 接口
• mod_lua：Lua 接口，可以调用其它模块接口
• mod_amqp：RabbitMQ 接口（Deprecated）
• mod_xcc：XCC 接口，使用 NATS 消息队列，推荐使用

XSwitch 支持多种 ASR 模块，包括但不限于：

• mod_unimrcp: TTS/ASR，MRCP 标准接口对接
• mod_baidu：TTS/ASR，百度
• mod_ali：TTS/ASR，阿里云
• mod_huawei：TTS/ASR，华为
• mod_xunfei：TTS/ASR，讯飞
• mod_bing：TTS，微软
• mod_speech：TTS/ASR，思必弛
• mod_tencent：TTS/ASR，腾讯（暂未实现）

语音识别中一项关键技术就是 VAD（即 Voice Activity Detection），检测到相关的语音才能进行下一步处理。

我们有专门的 VAD 库libxvad。

使用 C、Lua 等语言开发，可以使用任何语言进行二次开发。

• HTTP Hyper Text Transfer Protocol
• REST Representational State Transfer
• UUID Universal Unique IDentifer
• cURL cURL 是一个 HTTP 客户端库和实用工具，本文中大部分 HTTP 请求均使用它作例子
• XSwitch 软交换平台
• OpenSIPS SIP 代理服务器软件
• Kamailio SIP 代理服务器软件
• Websocket 双向通信接口
• VAD Voice Activity Detection，语音状态检测
• XSwitch 开源软交换系统和多媒体引擎
• XSwitch 基于 XSwitch 开发的软交换系统

AI 接口是基于 XSwitch 开发的，需要配套的 TTS/ASR 模块才能正常工作。XSwitch 本身不提供 TTS/ASR 功能，需要通过相关模块对接第三方的服务，如百度、阿里、讯飞的开放平台等。

AI 接口在 XSwitch 内部使用mod_ai实现，mod_ai依赖于 XSwitch 中的一些鉴权认证、消息发送等功能，这些功能在标准的 XSwitch 中不存在。当然mod_ai也可以移植到支持标准的 XSwitch，但需要打上相关补丁。

mod_ai和其它 ASR/TTS 模块支持 1.6 以上的 XSwitch，但是推荐使用 XSwitch 1.8 以上。

XSwitch AIAPI 认证鉴权方式与 Rest API 的鉴权方式一致。区别在于

• AI-API：访问路径/v1/
• Rest-API：访问路径/api/

根据后端配置，系统支持以下认证方式：

1. 无认证，或 IP 认证（通过iptables实现）
2. HTTP Basic 认证
3. X-XTRA-Auth-ID认证。

如果使用X-XTRA-Auth-ID认证，则使用前需要通过/api/sessions接口获取开发 Token：

POST /api/sessions

{
	"username": "user",
	"password": "pass"
}

返回：

{
	"token": "t-o-k-e-n",
	"expires": 0
}

如果系统启用了图形验证码，当用户名、密码错误超过指定次数后（默认两次），需要先获取图形验证码，再调用api/sessions，如下

GET /api/captchas

获取图形验证码 ID

{
	"message": "success",
	"code": 200,
	"data": {
		"captcha_id": 42,
		"pic_path": "/api/captchas/42"
	}
}

GET /api/captchas/42

根据验证码 ID 获取图形验证码图片，比如dOnW

再调用POST api/sessions

BODY 内容

{
    "login":"admin",
    "password":"xxxxx",
    "captcha_str":"dOnW"
}

其中 Token 是一个 UUID，在 XSwitch 运行期间有效，如果重启 XSwitch，则需要重新申请 Token。

在后续的 HTTP 请求头中携带X-XTRA-Auth-ID: t-o-k-e-n即可。

更多鉴权相关信息请参见《XSwitch 认证鉴权接口》。