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

API索引

接入方实现API

接口名	Method	描述
customized_url	POST	登录回调接口，由开发者实现

系统API

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

接口名	Method	描述
/account/login	POST	Credential登录小雅OS账户，获取osAccessToken
/account/third-login	POST	喜马拉雅账户登录小雅OS账户，获取osAccessToken
/account/sn-login	POST	无账号游客登录小雅OS账户，获取osAccessToken
/account/refresh-token	POST	刷新osAccessToken

语音接入层API

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

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

技能类API

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

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

API详情

接入方实现API

登录回调接口

接口定义：

METHOD: GET
URL: 由开发者生成，须填写到 开放平台 -> 硬件产品 -> 服务配置 的表单中(如下图)

验证 URL

请求参数

字段	类型	必填	说明
credential	String	是	第三方证书
sn	String	是	设备sn
productId	String	是	产品ID

返回值

字段	类型	必填	说明
openId	String	是	三方平台用户openId
name	String	否	用户名称
mobile	String	否	用户手机号
accessToken	String	否	三方平台访问令牌
refreshToken	String	否	三方平台刷新令牌
expiresIn	Int	否	三方平台有效期，单位：秒

系统API

Credential登录小雅OS账户，获取osAccessToken

接口定义：

METHOD: POST
URL: /account/login

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数
ptfId	String	是	第三方平台ID，在小雅OS开放平台生成
credential	String	是	第三方证书

返回值

字段	类型	说明
osAccessToken	String	小雅OS访问令牌
osRefreshToken	String	小雅OS刷新令牌
osExpiresIn	Long	小雅OS令牌过期时间，单位：秒，目前为7200秒

示例：

$ curl https://api.xiaoyastar.com/account/login?session=SESSION&params=PARAM_JSON&ptfId=os.ptf.xmly.test&credential=96e79218965eb72c92a549dd5a330112&sig=SIG

喜马拉雅账户登录小雅OS账户，获取osAccessToken

接口定义：

METHOD: POST
URL: /account/third-login

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数
ptfId	String	是	第三方平台ID，在小雅OS开放平台生成
thirdAccessToken	String	是	第三方访问令牌，不超过500字符
thirdOpenId	String	否	第三方开放平台ID，不超过100字符
thirdUid	Long	否	第三方用户ID

注意事项

根据对接账号体系的不同，thirdOpenId与thirdUid至少传其一。

返回值

字段	类型	说明
osAccessToken	String	小雅OS访问令牌
osRefreshToken	String	小雅OS刷新令牌
osExpiresIn	Long	小雅OS令牌过期时间，单位：秒，目前为7200秒

示例：

$ curl https://api.xiaoyastar.com/account/third-login?session=SESSION&params=PARAM_JSON&ptfId=os.pft.xmly.test&thirdAccessToken=96e79218965eb72c92a549dd5a330112&thirdUid=200628&sig=SIG

无账号游客登录小雅OS账户，获取osAccessToken

接口定义：

METHOD: POST
URL: /account/sn-login

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数

返回值

字段	类型	说明
osAccessToken	String	小雅OS访问令牌
osRefreshToken	String	小雅OS刷新令牌
osExpiresIn	Long	小雅OS令牌过期时间，单位：秒，目前为7200秒

示例：

$ curl https://api.xiaoyastar.com/account/sn-login?session=SESSION&params=PARAM_JSON&sig=SIG

刷新osAccessToken

接口定义：

METHOD: POST
URL: /account/refresh-token

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数
osRefreshToken	String	是	小雅OS刷新令牌

返回值

字段	类型	说明
osAccessToken	String	小雅OS访问令牌
osRefreshToken	String	小雅OS刷新令牌
osExpiresIn	Integer	小雅OS令牌过期时间，单位：秒，目前为7200秒

注意事项

此接口公共参数属性osAccessToken字段必填，填已有的osAccessToken。

示例：

$ curl https://api.xiaoyastar.com/account/refresh-token?session=SESSION&params=PARAM_JSON&osRefreshToken=96e79218965eb72c92a549dd5a330112&sig=SIG

语音接入类API

语音接入ASR和NLU

接口定义：

METHOD: WS
URL: /ws/stream-asr

请求参数

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

请求示例：

ws://xvs.xiaoyastar.com:80/ws/stream-asr
    ?requestId=fe7746f94a28426d888d13d64ece964a
    &params=%7B%27osClientId%27%3A%27os.client.sdkdemo%27%2C%27osAccessToken%27%3A%27eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcy5jbGllbnQuc2RrZGVtbyIsInVpZCI6MCwiaXNzIjoieHktb3MtdWNlbnRlciIsImV4cCI6MTU2MDQ4NjAwNywiZGV2aWNlSWQiOiJkZW1vLWRldmljZS1pZCJ9.fCk8Vx4hESR2JWIcvq1FcG_IBEVbaqhocXyR_vp0190%27%2C%27deviceType%27%3A1%2C%27productId%27%3A%27N_PROD1_7%27%2C%27sn%27%3A%27test%27%2C%27xn%27%3A%27781f7740%27%2C%27deviceId%27%3A%27demo-device-id%27%2C%27lat%27%3A%2712.3%27%2C%27lng%27%3A%2732%27%2C%27version%27%3A%271.2%27%2C%27osVersion%27%3A%272.3%27%2C%27dt%27%3A23123123123%2C%27sysType%27%3A1%2C%27appVersion%27%3A%271.0%27%2C%27sysVersion%27%3A%272.0%27%7D
    &type=0

语音二进制帧包格式

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: /voice/text2audio

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数
volume	String	否	0-9
rate	String	否	8,11,16,24,32,64
speed	String	否	0-9
speaker	String	否	0：小雅，20：儿童

返回值

MP3语音流

示例：

$ curl https://api.xiaoyastar.com/voice/text2audio?session=SESSION&params=PARAM_JSON&text=TEXT&sig=SIG

技能类API

根据文本获取NLU及SKILL结果

接口定义：

METHOD: GET
URL: /text/query

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数
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/text/query?session=SESSION&params=PARAM_JSON&text=TEXT&sig=SIG

根据指定意图获取SKILL结果

接口定义：

METHOD: GET
URL: /intent/invoke

请求参数

字段	类型	必填	说明
session	JsonObject	是	公共参数
params	JsonObject	是	公共参数
sig	String	是	公共参数
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/intent/invoke?session=SESSION&params=PARAM_JSON&intent=TEXT&sig=SIG