API 列表 · 小雅OS开放平台文档

API索引

系统API

域名调用 https://api.xiaoyastar.com

接口名	Method	描述
/serv/account/os-access-token	GET	获取osAccessToken
/serv/user	POST	注册小雅OS用户
/serv/query-times	POST	多渠道接入合作方，上报小雅OS请求次数及占比数据
/serv/unbind	POST	根据ptfId解绑三方平台账号，仅限技能登录账号

语音接入层API

域名调用
WebSocket协议： ws://xvs.xiaoyastar.com 
Http协议：      https://api.xiaoyastar.com

接口名	协议	Method	描述
/ws/serv/stream-asr	WebSocket		语音接入ASR和NLU
/serv/voice/text2audio	HTTP	GET	通过文字获取语音(TTS)

技能类API

域名调用：https://api.xiaoyastar.com

接口名	Method	描述
/serv/text/query	GET	根据文本获取NLU及SKILL结果
/serv/intent/invoke	GET	根据指定意图获取SKILL结果

API详情

系统API

获取osAccessToken

在访问小雅OS接口时，需要首先获得osAccessToken，作为鉴权凭证。

注意事项

1. 此接口在开放平台需要配置IP地址白名单才可以访问(暂时小雅OS技术支持辅助配置)。

2. 多次调用接口可以获得多个有效osAccessToken，每个有独立的过期时间。

3. 在多机部署时，请提供唯一的内部服务来管理osAccessToken。

4. 请不要频繁请求此接口，小雅OS仅保留最后5个osAccessToken，申请过多，会造成前面的申请的失效。

接口定义：

METHOD: GET
URL: /serv/account/os-access-token

请求参数

字段	类型	必填	说明
productId	String	是	产品 ID，开放平台分配
osServerSecret	String	是	对接密钥

返回值

字段	类型	说明
osAccessToken	String	获取到的访问令牌
osExpiresIn	Integer	凭证有效时间，单位：秒，目前为 7200 秒

示例：

$ curl https://api.xiaoyastar.com/serv/account/os-access-token?productId=xxx&osServerSecret=xxx

注册用户

小雅OS的部分接口，例如：/serv/text/query，使用osOpenId作为小雅OS用户标识。

接口定义：

METHOD: POST
URL: /serv/user

请求参数

字段	类型	必填	说明
osAccessToken	String	是	公共参数
ptfId	String	是	用户体系 ID，目前由小雅OS开发人员生成
openId	String	否	开发者用户 ID，开启同时登录技能选项时会在技能访问时使用
userId	Long	否	开发者用户ID
name	String	否	开发者用户真实姓名
mobile	String	否	开发者用户绑定的手机号
password	String	否	开发者用户密码
deviceId	String	否	设备ID
accessToken	String	否	开启同时登录技能选项时必填
refreshToken	String	否	开启同时登录技能选项时必填
expiresIn	Integer	否	开启同时登录技能选项时必填，accessToken 有效期，单位：秒

注意事项

同时登录技能表示设备开发者同时是技能提供方，使用除设备和小雅OS同步账号信息外，技能也是使用同步给小雅OS的账号信息来访问 登录喜马需传喜马用户信息：userId，deviceId，accessToken，refreshToken，expiresIn

返回值

字段	类型	说明
osOpenId	String	小雅 OS 用户唯一标识，永久不过期

示例：

$ curl https://api.xiaoyastar.com/serv/user?osAccessToken=OSACCESSTOKEN&openId=OPENID&ptfId=os.ptf.credential.test

解绑三方账号

解绑第三方登录账号，退出技能登录

接口定义：

METHOD: POST
URL: /serv/unbind

请求参数

字段	类型	必填	说明
osAccessToken	String	是	公共参数
ptfId	String	否	用户体系 ID，目前由小雅OS开发人员生成，不传默认退出喜马拉雅登录
osOpenId	String	是	小雅OS用户标识

返回值

字段	类型	说明
errno	Integer	错误码，0-成功

请求次数上报

上传数据的方式有两种：文件上传和JSONArray上传

文件上传格式如下：

sn，osQueryTimes，totalQueryTimes

N0001，10，20

N0002，11，20

N0003，12，20

...

JSONArray上传将Json格式的数据转为字符串，通过data字段上传，格式如下：

[{"sn":"N0001","osQueryTimes":10, "totalQueryTimes":20},{"sn":"N0002","osQueryTimes":11, "totalQueryTimes":20},{"sn":"N0003","osQueryTimes":12, "totalQueryTimes":20}]

接口定义：

METHOD: POST
URL: /serv/query-times

请求参数

字段	类型	必填	说明
osAccessToken	String	是	公共参数
productId	String	是	产品ID
dt	String	是	日期字符串，格式yyyy-MM-dd
file	File	否	文件格式数据
data	JsonArray	否	json格式数据

注意事项

此接口Header Content-Type应为multipart/form-data

返回值

字段	类型	说明
num	Integer	成功上传的数据条数
success	Boolean	是否成功

语音接入类API

语音接入ASR和NLU

接口定义：

Method: WS
URL: /ws/serv/stream-asr

请求参数

QUERY参数	类型	必填	说明
osAccessToken	String	是	公共参数
params	JsonObject	是	公共参数
requestId	String	是	session id，由客户端生成，代表一次会话唯一ID，可随机生成
type	Integer	否	音频编码格式，默认0; 0：pcm(16K采样率，16bit位宽，单通道）1：opus(16K采样率，32K码率）
asrPid	Integer	否	0：近场 1：远场

请求示例：

ws://xvs.xiaoyastar.com:80/ws/serv/stream-asr
    ?requestId=fe7746f94a28426d888d13d64ece964a
    &params=%7B%22deviceType%22%3A1%2C%22productId%22%3A%22N_PROD1_7%22%2C%22sn%22%3A%22test%22%2C%22xn%22%3A%22781f7740%22%2C%22deviceId%22%3A%22demo-device-id%22%2C%22lat%22%3A%2212.3%22%2C%22lng%22%3A%2232%22%2C%22version%22%3A%221.2%22%2C%22osVersion%22%3A%222.3%22%2C%22dt%22%3A23123123123%2C%22sysType%22%3A1%2C%22appVersion%22%3A%221.0%22%2C%22sysVersion%22%3A%222.0%22%7D
    &type=0
    &osAccessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9kdWN0SWQiOiJOX1BST0QxXzciLCJpc3MiOiJ4eS1vcy11Y2VudGVyIiwiZXhwIjoxNTYzNzk5NDk1LCJvc0NsaWVudElkIjoib3MuY2xpZW50LnNka2RlbW8ifQ.GdgB_U_plnVgc0WOYrC3hvtOELfCyekseNajg3VApCA

语音二进制帧包格式

playload中需要包含pcm格式，采样率16k，采样数据用 16bit记录，每个数据包可以为固定时间（如：60ms）内的语音数据。

尾包

使用文本帧，传输json，需要包含以下字段:

json参数	类型	必填	说明
pkgNum	Integer	是	语音包的数量
code	String	是	传2
msg	String	是	传end

示例:

{"pkgNum": 2, "code": 2, "msg": "end"}

返回值

字段	类型	说明
asrResponse	JsonObject	asr结果集
nluResponse	JsonObject	nlu结果集
type	String	ASR，NLU
success	Boolean	是否成功，true或者false
errorCode	String	错误码
errorMsg	String	错误消息

asrResponse语音响应包

字段	类型	说明
endFlag	Integer	识别结束标识：0为中间识别结果，1最终识别结果
errorNo	Integer	错误号(成功0，失败为负值)
idx	Integer	第n个数据包产生的识别结果
result	JsonObject	识别结果对象
result.nbest	String	识别结果的文本
requestId	String	requestId

语音响应示例：

{"asrResponse":{"result":{"nbest":["明"]},"errNo":0,"endFlag":0,"idx":24,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天"]},"errNo":0,"endFlag":0,"idx":29,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天天"]},"errNo":0,"endFlag":0,"idx":34,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天天气"]},"errNo":0,"endFlag":0,"idx":36,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天天气怎"]},"errNo":0,"endFlag":0,"idx":41,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天天气怎么"]},"errNo":0,"endFlag":0,"idx":43,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天天气怎么样"]},"errNo":0,"endFlag":0,"idx":48,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}
{"asrResponse":{"result":{"nbest":["明天天气怎么样"]},"errNo":0,"endFlag":1,"idx":-9999,"sid":"3a34881653684f9da51fcc540c9f8de1"},"requestId":"3a34881653684f9da51fcc540c9f8de1","success":true,"type":"ASR"}

nluResponse资源响应包

使用文本帧，playload里包含json字符串，字段如下

字段	类型	必填	说明
version	String	是	版本号
session	JsonObject	是	会话信息
session.sid	String	是	session id
session.attributes	JsonObject	否	会话属性，部分技能可能有值，key-value形式，key为string，value为object
nlu	JsonArray	是	nlu结果，列表形式，参见技能业务数据
nlu.domain	String	是	识别后的领域，参见技能业务数据
nlu.intent	String	是	识别后的意图
nlu.slots	JsonObject	是	识别后的槽位，key-value形式，key为string，value为object，参见技能业务数据
response	JsonObject	是	结果对象，用于告知客户端该如何操作
response.outputSpeech	JsonObject	是	tts对象，包含tts内容
response.outputSpeech.type	String	是	tts类型，目前包括PlainText、SSML
response.outputSpeech.text	String	否	tts内容，若type为PlainText必须该字段必须有值
response.outputSpeech.ssml	String	否	SSML格式的tts内容，若type为SSML必须该字段必须有值
response.outputSpeech.playBehavior	String	否	行为控制，默认都为ENQUEUE，代表追加
response.card	JsonObject	否	技能携带的伴侣APP上显示的卡片信息，见card
response.directives	JsonArray	是	指令列表，参见指令数据
response.directives.type	String	是	指令类型
response.data	JsonObject	是	包含技能业务数据，具体格式由技能业务定义，不同技能返回的数据格式可能不同，参见技能业务数据
response.shouldEndSession	boolean	否	是否需要结束当前会话, 默认true，如果为false设备端可开启继续拾音

注意事项

请根据返回值中NLU节点中的domain，intent，slots来确定response.data中的数据

资源包返回示例：

{
    "version": "1.0.0",
    "session": {
        "sid": "1111",
        "attributes": {
            "key": "value"
        }
    },
    "nlu":[{
        "domain": "music",
        "intent": "play",
        "slots":{}
    }],
    "response":{
        "outputSpeech": {
            "type": "PlainText",
            "text": "Plain text string to speak",
            "ssml": "<speak>SSML text string to speak</speak>",
            "playBehavior": "ENQUEUE"
        },
        "directives": [
            {
                "type": "AudioPlay.Play",
                "audioItem": {
                    "stream": {
                        "url": "http://live.xmcdn.com/live/1066/64.m3u8",
                        "token": null,
                        "offsetInMilliseconds": 0 
                    },
                    "metaData": {
                        "id": "182372",
                        "title": "倾听全球",
                        "albumId": "1066",
                        "albumTitle": "CNR经济之声",
                        "artist": null,
                        "art": {
                            "small": "http://fdfs.xmcdn.com/group28/M0A/30/29/wKgJSFkxRYGDCbimAADGj2hAjb0694_mobile_small.jpg",
                            "middle": "http://fdfs.xmcdn.com/group28/M0A/30/29/wKgJSFkxRYGDCbimAADGj2hAjb0694_mobile_small.jpg",
                            "large": "http://fdfs.xmcdn.com/group28/M0A/30/29/wKgJSFkxRYGDCbimAADGj2hAjb0694_mobile_large.jpg"
                        }
                    }
                },
                "playBehavior": "ENQUEUE"
            }
        ],
        "data": {
            "resSoundState": "101",// 该字段仅在喜马拉雅技能返回时存在
            "resSoundData": { // 该字段仅当 resSoundState 存在 且 resSoundState 值为1开头时存在
                "contentType": "1", // 资源类型 1 内容资源 2 电台资源
                "radioId": "12", // 该字段contentType 为2 时存在，电台id
                "scheduleId": "45837", // 该字段contentType 为2 时存在，广播电台时间表id
                "albumId": "5080817", // 该字段contentType 为1 时存在，专辑id
                "trackId": "20297910", // 该字段contentType 为1 时存在，声音id
                "source": "fm/ximalaya",// 资源来源， {技能标识}/{资源来源}
                "album": { // contentType 为 1 时存在，专辑详情
                    "playCount": 111111, // 专辑播放量
                    "isPaid": 0, // 是否付费，0是免费专辑
                    "isVipFree": 0 // 是否vip免费，1是vip免费
                },
                "track": { // contentType 为 1 时存在，声音详情
                    "playCount": 111111, // 声音播放量
                    "isFree": 0 // 是否支持试听，1是支持试听
                }
            },
            "searchResult": { 
                // 搜索结果列表，如果需要这一项请联系商务开通，开通后响应时间会有少许的增加
                // 该字段仅当 resSoundState 存在 且 resSoundState 值为1开头时有值
               "kind" : "album", //搜索类型，值有album以及track
               "list" : [
                    // 当kind为album时，此处为album对象的列表,album对象详见 http://open.xiaoyastar.com/os/docs/server/api/entity.html#Album
                    // 当kind为track时，此处为track对象的列表,track对象详见 http://open.xiaoyastar.com/os/docs/server/api/entity.html#Track
                    // 当前列表不支持分页，且返回条数不超过20条，并可能包含AudioPlay.Play指令中返回的资源
               ]
            }
        },
        "shouldEndSession": true
    }
}

返回统一异常

其中error_no取值描述信息如下：

错误码	描述信息
3001	voice内部错误
3002	参数请求错误
3003	鉴权失败
3004	第三方错误
3005	语音包错误
3006	语音包识别为空

错误示例

{"errorCode":"3003","errorMsg":"调用鉴权接口异常:500 null","success":false,"type":"ASR"}

TTS 文字转换语音

接口定义：

METHOD: GET
URL: /serv/voice/text2audio

请求参数

字段	类型	必填	说明
osAccessToken	String	是	公共参数
params	JsonObject	是	公共参数
text	String	是	需要转换成语音的文本

返回值

MP3语音流

示例：

$ curl https://api.xiaoyastar.com/serv/voice/text2audio?osAccessToken=OS_ACCESS_TOKEN&params=PARAM_JSON&text=TEXT

技能类API

根据文本获取NLU及SKILL结果

接口定义：

METHOD: GET
URL: /serv/text/query

请求参数

字段	类型	必填	说明
osAccessToken	String	是	公共参数
params	JsonObject	是	公共参数
text	String	是	查询文本

返回值

字段	类型	必填	说明
version	String	是	版本号
session	JsonObject	是	会话信息
session.sid	String	是	session id
session.attributes	JsonObject	否	会话属性，部分技能可能有值，key-value形式，key为string，value为object
nlu	JsonArray	是	nlu结果，列表形式，参见技能业务数据
nlu.domain	String	是	识别后的领域，参见技能业务数据
nlu.intent	String	是	识别后的意图
nlu.slots	JsonObject	是	识别后的槽位，key-value形式，key为string，value为object，参见技能业务数据
response	JsonObject	是	结果对象，用于告知客户端该如何操作
response.outputSpeech	JsonObject	是	tts对象，包含tts内容
response.outputSpeech.type	String	是	tts类型，目前包括PlainText、SSML
response.outputSpeech.text	String	否	tts内容，若type为PlainText必须该字段必须有值
response.outputSpeech.ssml	String	否	SSML格式的tts内容，若type为SSML必须该字段必须有值
response.outputSpeech.playBehavior	String	否	行为控制，默认都为ENQUEUE，代表追加
response.card	JsonObject	否	技能携带的伴侣APP上显示的卡片信息，见card
response.directives	JsonArray	是	指令列表，参见指令数据
response.directives.type	String	是	指令类型
response.data	JsonObject	是	包含技能业务数据，具体格式由技能业务定义，不同技能返回的数据格式可能不同，参见技能业务数据
response.shouldEndSession	Boolean	否	是否需要结束当前会话, 默认true，如果为false设备端可开启继续拾音

注意事项

请根据返回值中NLU节点中的domain，intent，slots来确定response.data中的数据

{
    "version": "1.0.0",
    "session": {
        "sid": "1111",
        "attributes": {
            "key": "value"
        }
    },
    "nlu":[{
        "domain": "music",
        "intent": "play",
        "slots":{}
    }],
    "response":{
        "outputSpeech": {
            "type": "PlainText",
            "text": "Plain text string to speak",
            "ssml": "<speak>SSML text string to speak</speak>",
            "playBehavior": "ENQUEUE"
        },
        "directives": [
            {
                "type": "AudioPlay.Play",
                "audioItem": {
                    "stream": {
                        "url": "http://live.xmcdn.com/live/1066/64.m3u8",
                        "token": null,
                        "offsetInMilliseconds": 0 
                    },
                    "metaData": {
                        "id": "182372",
                        "title": "倾听全球",
                        "albumId": "1066",
                        "albumTitle": "CNR经济之声",
                        "artist": null,
                        "art": {
                            "small": "http://fdfs.xmcdn.com/group28/M0A/30/29/wKgJSFkxRYGDCbimAADGj2hAjb0694_mobile_small.jpg",
                            "middle": "http://fdfs.xmcdn.com/group28/M0A/30/29/wKgJSFkxRYGDCbimAADGj2hAjb0694_mobile_small.jpg",
                            "large": "http://fdfs.xmcdn.com/group28/M0A/30/29/wKgJSFkxRYGDCbimAADGj2hAjb0694_mobile_large.jpg"
                        }
                    }
                },
                "playBehavior": "ENQUEUE"
            }
        ],
        "data": {
            "resSoundState": "101",// 该字段仅在喜马拉雅技能返回时存在
            "resSoundData": { // 该字段仅当 resSoundState 存在 且 resSoundState 值为1开头时存在
                "contentType": "1", // 资源类型 1 内容资源 2 电台资源
                "radioId": "12", // 该字段contentType 为2 时存在，电台id
                "scheduleId": "45837", // 该字段contentType 为2 时存在，广播电台时间表id
                "albumId": "5080817", // 该字段contentType 为1 时存在，专辑id
                "trackId": "20297910", // 该字段contentType 为1 时存在，声音id
                "source": "fm/ximalaya",// 资源来源， {技能标识}/{资源来源}
                "album": { // contentType 为 1 时存在，专辑详情
                    "playCount": 111111, // 专辑播放量
                    "isPaid": 0, // 是否付费，0是免费专辑
                    "isVipFree": 0 // 是否vip免费，1是vip免费
                },
                "track": { // contentType 为 1 时存在，声音详情
                    "playCount": 111111, // 声音播放量
                    "isFree": 0 // 是否支持试听，1是支持试听
                }
            },
            "searchResult": { 
                // 搜索结果列表，如果需要这一项请联系商务开通，开通后响应时间会有少许的增加
                // 该字段仅当 resSoundState 存在 且 resSoundState 值为1开头时有值
               "kind" : "album", //搜索类型，值有album以及track
               "list" : [
                    // 当kind为album时，此处为album对象的列表,album对象详见 http://open.xiaoyastar.com/os/docs/server/api/entity.html#Album
                    // 当kind为track时，此处为track对象的列表,track对象详见 http://open.xiaoyastar.com/os/docs/server/api/entity.html#Track
                    // 当前列表不支持分页，且返回条数不超过20条，并可能包含AudioPlay.Play指令中返回的资源
               ]
            }
        },
        "shouldEndSession": true
    }
}

示例：

$ curl https://api.xiaoyastar.com/serv/text/query?osAccessToken=OS_ACCESS_TOKEN&params=PARAM_JSON&text=TEXT

根据指定意图获取SKILL结果

接口定义：

METHOD: GET
URL: /serv/intent/invoke

请求参数

字段	类型	必填	说明
osAccessToken	String	是	公共参数
params	JsonObject	是	公共参数
intent	JsonObject	是	意图文本，参见指令数据
intent.domain	String	是	技能领域
intent.intent	String	是	技能意图
intent.slots	JsonObject	否	访问技能接口时需要的业务参数，由key-value组成的对象

返回值

字段	类型	必填	说明
version	String	是	版本号
session	JsonObject	是	会话信息
session.sid	String	是	session id
session.attributes	JsonObject	否	会话属性，部分技能可能有值，key-value形式，key为string，value为object
nlu	JsonArray	是	nlu结果，列表形式，参见指令数据
nlu.domain	String	是	识别后的领域，参见指令数据
nlu.intent	String	是	识别后的意图
nlu.slots	JsonObject	是	识别后的槽位，key-value形式，key为string，value为object，参见指令数据
response	JsonObject	是	结果对象，用于告知客户端该如何操作
response.outputSpeech	JsonObject	是	tts对象，包含tts内容
response.outputSpeech.type	String	是	tts类型，目前包括PlainText、SSML
response.outputSpeech.text	String	否	tts内容，若type为PlainText必须该字段必须有值
response.outputSpeech.ssml	String	否	SSML格式的tts内容，若type为SSML必须该字段必须有值
response.outputSpeech.playBehavior	String	否	行为控制，默认都为ENQUEUE，代表追加
response.card	JsonObject	否	技能携带的伴侣APP上显示的卡片信息，见card
response.directives	JsonArray	是	指令列表，参见指令数据
response.directives.type	String	是	指令类型
response.data	JsonObject	是	包含技能业务数据，具体格式由技能业务定义，不同技能返回的数据格式可能不同，参见指令数据
response.shouldEndSession	Boolean	否	是否需要结束当前会话, 默认true，如果为false设备端可开启继续拾音

示例：

$ curl https://api.xiaoyastar.com/serv/intent/invoke?osAccessToken=OS_ACCESS_TOKEN&params=PARAM_JSON&intent=TEXT