技能请求接口 | 微信开放文档

# 技能请求接口

所有的文本请求都可以走技能请求接口，但是相关的技能权限需要在官网进行申请，当前支持技能：音乐、FM、新闻、百科、闲聊、闹钟、天气、股票。各技能的query文本示例如下表：

# query示例

query	技能
播放周杰伦的稻香	音乐
播放郭德纲的相声	FM
科技新闻	新闻
世界最长的河流	百科
陪我聊天	闲聊
帮我订一个下午五点的闹钟	闹钟
今天北京的天气怎么样	天气
腾讯股价	股票
下一首	通用控制

# 请求

请求地址： https://{BASE_URL}/xwcloudapi/text_to_skills

请求方式： post

# 请求参数

请求参数包含三部分：请求query文本、请求接口基础参数、当前播放状态state_info。请求query文本示例如上表所示；请求接口基础参数相关描述见请求接口基础参数说明章节；

技能请求必须携带state_info。对于通用控制的请求，需要依赖state_info.cur_res_info.skill_name进行判断是那个技能的通用控制，比如下一首，依赖state_info.cur_res_info.skill_name进行判断是音乐技能的下一首还是FM技能的下一首。虽然state_info字段只有通用控制（"收藏"、"取消收藏"、"播放收藏"、"下一首","上一首","暂停","继续播放","重播","单曲循环","顺序播放","循环播放","随机播放","快进","快退","音量大一点","音量小一点","静音","取消静音"）的请求使用，但是在访问技能请求接口之前，无法确定是否为通用控制的请求，所以必须带上当前设备的播放状态state_info相关参数，尽量把可以获取到的参数带上，尤其是cur_res_info中的参数，避免通用控制不生效。

对于state_info，必须携带state_info.client_addr字段。由于音乐资源地区版权问题，Q音要求请求需要携带客户端ip，用于判断客户所在地区。如果无法获取用户客户端ip，请与小微商务进行提前沟通。state_info 的字段组成如下：

field name	field type	required	desc
cur_res_info	json object	No	当前播放资源信息，详细信息见下文
location_info	json object	No	位置信息，详细信息见下文
gps_info	json object	No	GPS信息，详细信息见下文
client_addr	string	Yes	客户端ip地址
play_mode	int	No	0：顺序播放 1：列表循环 2：随机不循环 3：随机循环 4：单曲循环
play_state	int	No	1：歌曲开始 2：暂停 3：歌曲结束 4：歌单结束 11：没播完切歌
curent_time	int	No	上报时间

其中cur_res_info中字段如下

field name	field type	required	desc
skill_name	string	No	技能名称，请求到资源时会传回技能名称
res_id	string	No	资源id
res_name	string	No	资源名，可以使用music_name字段
res_singer	string	No	演唱者
content	string	No	资源url
time_offset_ms	int	No	播放时间偏移

其中location_info 中字段如下：

field name	field type	required	desc
contry	string	NO	国家
province	string	NO	省份
city	string	NO	城市
street	string	NO	街道
community	string	NO	社区

其中gps_info 中字段如下：

field name	field type	required	desc
altitude	double	NO	海拔高度
latitude	double	NO	纬度
longitude	double	NO	经度
speed	double	NO	速度
standard_gps_time	int	NO	标准gps时间

# 一个请求示例

目前推荐使用方式二：获取安全凭据接口获取凭证，所以请求示例都以此方式进行描述。如果仍然使用方式一获取凭证，请求示例中的pid、auth、query_id去掉，增加base_info字段，base_info相关描述详见基础说明章节。所有技能的请求格式一致，各技能对应的query不同，通过方式二获取安全凭据访问技能请求接口请求示例如下：

{
    "query": "我想听周杰伦的稻香",
		
    // 请求接口基础参数
    "pid": 324,
    "auth": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYXNlX2luZm8iOiJ7XCJjb2RlXCI6XCIwN2E0YTZlNTRlMDUwMjRlYmQ0MTMzMzM5Y2M3OTAzMFwiLFwicGlkXCI6ODIzOTIzNDc4LFwidGltZXN0YW1wXCI6XCIxNTk4NTk5NzA1XCJ9XG4iLCJleHAiOjE1OTg2MDY5MDV9.nBuDFO7CWfg9KLognHIy10WFIorzuMBBRNh_F8gSXY",
    "query_id": "KLDASOEWUROUQWIOEUROWEQVNZVFADSFOIOUWOEQR",
		
	// state_info相关参数
    "state_info": { 
        "cur_res_info":{ 
            "skill_name": "Music",
            "res_id": "unique_id=7091652&type=cur",
            "res_name": "冰雨",
            "res_singer": "刘德华",
            "content": "http://isure.stream.qqmusic.qq.com/C200002DMN9H2rxulA.m4a?guid=12347310&vkey=B0D71E80BF0CF55081A4DE84C2881F5E486D1A37EECA3DE2C6782E87359DF30013688A13102AC4B3BD6EF837D3E91E6CEEECFCA7BB77C467&uin=&fromtag=50",
            "time_offset_ms": 3053 
        } ,
        "client_addr": "192.168.134.12",
        "play_mode": 1,
        "play_state": 1,
        "curent_time": 1591172141
    }
}

注意：对于音乐技能的请求：没有通过注册音乐资源登录态接口注册登录态的用户，小微音乐技能只对其支持随心听的 query，对于已经通过注册音乐资源登录态接口注册登陆态的用户，除了随心听的query，还会支持语义点播，比如播放指定歌手、指定音乐等query。

音乐随心听的query可以是"我想听音乐"、"我想听歌"、"播放音乐"等。请求方式与下面音乐技能请求示例参数相同，返回数据格式相同。

# 结果返回

返回结果包含四部分：code错误码提示、resources获取相关资源、skill技能名称、msg错误提示。

对于返回的技能，通过skill字段进行判断。skill包含以下技能取值：

# skill取值

skill取值	含义
Baike	百科技能
Chat	小微闲聊
News	新闻
Music	音乐
FM-Crosstalk	FM-相声
FM-Story	FM-故事
FM-Station	FM-电台
FM-Joke	FM-笑话
FM-Comments	FM-评书
FM-Novel	FM-小说
Clock	闹钟
CommCtrl	通用控制
Weather	天气
Stock	股票

# code错误码说明

技能	错误码值	说明
音乐技能相关	0	成功
	52000	未知错误
	52001	音乐系统错误，一般不会遇到
	52002	音乐系统错误，一般不会遇到
	52003	请求音乐服务的相关参数错误。
	52004	请求的音乐资源不存在
	52005	音乐账号未授权
	52006	音乐授权信息校验失败
	52007	音乐授权信息已经过期
	52008	请求音乐相关接口超限，一般是请求频率太高。
	52009	当前账户没有访问该资源权限。
	52010	没有登录
	52011	付费歌曲，非绿钻或付费包会员不能播放
	52012	没找到指定的歌手或者歌曲
	52013	因歌曲没有版权不能播放
	52014	没找到任何歌曲
	52015	因海外地区不能播放
	52016	因歌曲为数字专辑歌曲不能播放
	52017	设备的基础会员过期
	52018	预拉取资源：没有更多数据
	52019	预拉取资源：res_id不存在
	52020	创建歌单内所有歌曲都没有版权
FM技能相关	54001	FM服务失败
新闻技能相关	55001	新闻服务失败
百科技能相关	56001	百科服务失败

# resources资源字段说明

不同的技能返回的资源字段会有差别。音乐技能与FM技能返回的数据如下所示。

音乐技能请求返回

{
	"code": 0,
	"data": {
		"resources": [{
			"attach_info": "{}",
			"duration": 136,
			"extend_buf": "eyJleHBpcnlfdGltZSI6MTU4NDE0ODQ2OX0=",
			"mid": "003fhlM30c0ZQE",
			"music_album_name": "所有你想听的翻唱",
			"music_cover_url": "http://y.gtimg.cn/music/photo_new/T002R500x500M0000023ZJ4K3Qo5mL_1.jpg",
			"music_name": "我又初恋了",
			"music_singer": "小心怪兽",
			"play_count": -1,
			"playable": 1,
			"res_content": "http://isure.stream.qqmusic.qq.com/C200003vXWKk1BvPSf.m4a?guid=12347310&vkey=D7FE9A072A6CB4541C8989A31F14DA0E9A9E7E24F45CEDE48416EE71C5DB28043E4D26D44F45027057884B86AC8DB142C76CC0B25B9B6110&uin=&fromtag=50",
			"res_id": "unique_id=127136854&type=cur",
			"hot":1
		}, 
            ......// 省略歌曲信息
    ],
		"skill": "Music",
		"tts": "好的，请听小心怪兽，我又初恋了"
	},
	"msg": "OK"
}

FM技能请求返回

{
	"code": 0,
	"data": {
		"resources": [{
			"duration": 3510,
			"music_album_name": "坑王驾到",
			"music_cover_url": "http://imgcache.qq.com/fm/photo/programe/rmid_programe_360/y/4/000y0a0t3APty4.jpg?time=1524562574",
			"music_name": "探地穴（一）异僧豪夺香楠木 员外梦走大罗天",
			"music_singer": "相声小品休闲茶馆",
			"play_count": -1,
			"playable": 1,
			"res_content": "http://ws.stream.fm.qq.com/R196000y0a0t3APty4.m4a?fromtag=36&guid=1584065658&vkey=056F583736D957885FDCC2B741E3D02C46C11E4F700CB87A321A41F8252C6EF623FD2623677CA5919745001C844C9B9A889C3717B1378A12",
			"res_id": "unique_id=rd000y0a0t3APty4&type=3&album_id=rd003q4BfU3HYZaO&show_sequence=1"
		},
            ......// 省略相声信息
  	],
		"skill": "FM",
		"tts": "好的，为你播放 坑王驾到 探地穴（一）异僧豪夺香楠木 员外梦走大罗天"
	},
	"msg": "OK"
}

音乐、FM技能resources描述如下表所示：

字段	含义
duration	时长
extend_buf	歌词等信息的扩展字段，业务自定义*
mid	音乐的mid
music_album_name	专辑
music_cover_url	封面图片
music_name	歌曲名
music_singer	歌手名
play_count	播放次数，默认是0，如果是一次性的，为1
playable	是否可播放0：否，1：是
res_content	资源url
res_id	资源id
hot	是否收藏 0：未收藏 1：已收藏

新闻技能请求返回

{
	"code": 0,
	"data": {
		"resources": [{
			"music_cover_url": "http://inews.gtimg.com/newsapp_ls/0/12516970228_640330/0",
			"pub_time": "1600913688",
			"res_content": "http://media.dreamreader.qq.com/1101_2bad8d0d638f28d381682b47e0da06c1.f0.mp3?vkey=0FE9BE41145BE11B2E4030D2495FFD3EB08115A69C141FD39385C764F18E52AA5F06129C06BA0001276DD969DB25AED41FF15B04B86BCD6AECE383975FD480ED3934DE55D8234775E44F829E4B332815C9EA46B6016367C9&appid_sign=509029a5d5b7dd335551055048d0b6ee&appid_sign_timestamp=1600915153&appid=yunxiaowei&duration=55",
			"res_id": "20200924A03T46",
			"source": "有车以后",
			"summary": "上汽集团，一直以来在研发自动驾驶方面都非常积极，而且最新的技术产品对于我们消费者来说门槛也不高。这次体验的荣威i6 MAX，指导价为10.98-12.58万，即可体验到搭载上汽最新L2.5级的智能驾驶辅助系统。荣威i6 MAX，采用了荣威最新的设计语言，前格栅采用了“荣鳞展翼”造型设计，看上去非常立体且富有层次感，辨识度很高，同时，格栅上还有一个荧光绿/黄的“R标识”，保险杠两侧也有同样色彩鲜艳的色彩点缀，进一步提高前脸的辨识度。8.3秒破百的成绩对于它顶配不到13万的价格来说，也是挺诱人的。",
			"title": "8.3s破百、10万级售价，还有L2.5自动驾驶，荣威i6 MAX香吗"
		}, {
			"music_cover_url": "http://inews.gtimg.com/newsapp_ls/0/12516903419_640330/0",
			"pub_time": "1600912873",
			"res_content": "http://media.dreamreader.qq.com/1101_7a3b0a5264655ae092b83c976409f060.f0.mp3?vkey=B7404ECB1B3B00DB3E07B01041B9283C38B9ECB36C573EE859772EC3497BDF4A49881DC217914AB8829449A8BDCA6E05422B70C516FFBC4F19500D81D1C36ECC85CEFFF50C0F0A8A1B94B3BCC02BF7C527702E20CCF3A13A&appid_sign=509029a5d5b7dd335551055048d0b6ee&appid_sign_timestamp=1600915153&appid=yunxiaowei&duration=61",
			"res_id": "20200924A03G8A",
			"source": "功夫汽车",
			"summary": "很多人多土豪有很多误解，最明显的一个就是土豪的车一定都是特别贵的，不上大几十万都不成。虽然汉兰达的地位如日中天，但是真正的土豪最喜欢的却不是它，而是另一个十分给力的硬茬：大众途昂。在市场销量上今年8月份大众途昂已经卖出了7740台，在国内SUV市场排名33，不过在中大型SUV领域它已经排名第一，稳坐榜首。在国内消费者对于大众SUV的认可度是比较高的，而在外观部分相比汉兰达途昂的优势更加明显。车身尺寸上它的长宽高分别为5039、1989、1773毫米，轴距为2980毫米。这台合资SUV比汉兰达硬气，低配只要22万多，各位有想法吗？",
			"title": "土豪都喜欢的合资SUV，轴距3米同级销冠，不贵还带全时四驱"
		}],
		"skill": "News",
		"tts": "好的，为你播放新闻"
	},
	"msg": "OK"
}

新闻resources描述如下表所示：

字段	含义
res_content	新闻资源url
res_id	新闻id
music_cover_url	图片url
pub_time	发布时间
source	新闻来源
summary	摘要
title	标题

百科、股票、闲聊、天气技能请求返回

{
	"code": 0,
	"data": {
		"resources": [{
			"content": "周杰伦(Jay Chou,别名:杰伦,1979年1月18日-),出生于中国台湾新北市,毕业于淡江中学,中国台湾男歌手、演员、导演。2000年被吴宗宪发掘并推出首张专辑《Jay》。2005年涉足影视,以电影《头文字D》获第42届台湾电影金马奖及第25届香港电影金像奖“最佳新人”奖。2007年,自编自导自演的电影《不能说的秘密》获得台湾电影金马奖年度台湾杰出电影奖。2011年凭借专辑《跨时代》获得金曲奖最佳国语男歌手奖,并且第4次获得金曲奖最佳国语专辑奖。2020年10月24日,将举办嘉年华世界巡回演唱会澳洲悉尼站。"
		}],
		"skill": "Baike",
		"tts": "周杰伦(Jay Chou,别名:杰伦,1979年1月18日-),出生于中国台湾新北市,毕业于淡江中学,中国台湾男歌手、演员、导演。2000年被吴宗宪发掘并推出首张专辑《Jay》。2005年涉足影视,以电影《头文字D》获第42届台湾电影金马奖及第25届香港电影金像奖“最佳新人”奖。2007年,自编自导自演的电影《不能说的秘密》获得台湾电影金马奖年度台湾杰出电影奖。2011年凭借专辑《跨时代》获得金曲奖最佳国语男歌手奖,并且第4次获得金曲奖最佳国语专辑奖。2020年10月24日,将举办嘉年华世界巡回演唱会澳洲悉尼站。"
	},
	"msg": "OK"
}

content字段为请求返回的内容，百科、股票、闲聊、天气skill技能名称可取Baike、Chat、Stock、Weather。

通用控制请求返回

通用控制包括（"收藏"、"取消收藏"、"播放收藏"、"下一首","上一首","暂停","继续播放","重播","单曲循环","顺序播放","循环播放","随机播放","快进","快退","音量大一点","音量小一点","静音","取消静音"）。

播放收藏只会播放音乐技能、FM技能的收藏，返回资源的数据格式与FM技能请求、音乐技能请求返回的数据格式相同。其他的通用控制返回contrl_id、contrl_value两个字段代表不同的通用控制。返回的数据格式如下所示：

{
	"code": 0,
	"data": {
		"resources": [{
			"contrl_id": 1100010,
			"contrl_value": "unique_id=rd001LMIZE0Tfw5z&type=3&album_id=rd0027ZnyD1YChkU&show_sequence=1"
		}],
		"skill": "FM-Crosstalk",
		"tts": "已收藏，你也可以让我取消收藏"
	},
	"msg": "OK"
}

通用控制的各个功能与contrl_id、contrl_value的对应关系，如下表所示：

function	contrl_id	contrl_value
收藏	1100010	资源id
取消收藏	1100011	资源id
下一首	1000015	空
上一首	1000014	空
暂停	1000012	空
继续播放	1000010	空
重播	1000013	资源id
单曲循环	1000019	4
顺序播放	1000019	0
循环播放	1000019	1
随机播放	1000019	3
快进	1000017	5000
快退	1000017	-5000
音量大一点	1000000	10
音量小一点	1000000	-10
静音	1000002	空
取消静音	1000003	空

闹钟技能请求返回

{
    "code":0,
    "data":{
        "resources":[
            {
                "clock_id":36850,
                "clock_type":0,
                "event":"",
                "opt":1,
                "repeat_interval":"",
                "repeat_type":0,
                "service_type":0,
                "trig_time":1591174800
            }],
        "skill":"Clock"
    },
    "msg":"OK"
}

闹钟技能返回资源字段说明如下表：

字段	说明
clock_id	闹钟id （闹钟id+type唯一确定一个闹钟）
clock_type	1.一次性闹钟 2.重复闹钟
event	事件，为空标示没有事件
opt	设置闹钟的操作方式：1增加 2修改 3删除 4.修改闹钟类型
repeat_interval	闹钟重复类型的字符串，例如，"1111111"代表一周七天
repeat_type	闹钟重复类型，1表示每天一次、2表示每周一次、3表示每月一次
service_type	0：本地，1：定时播放 2：定时关闭skill，默认本地
trig_time	触发时间