语音平台接入

更新时间:2025-05-30 01:56:03下载pdf

API 列表

Method API Token type Description
GET /v1.0/iot-02/third-voice-config/customer-skills 全局令牌 获取客需技能字典
GET /v1.0/iot-02/third-voice-config/custom-qas 全局令牌 获取自定义问答
GET /v1.0/voice/devices/{voice_id}/token 全局令牌 获取语音令牌
GET /v1.0/token/{refresh_token} 语音令牌 刷新语音令牌
DELETE /v1.0/voice/devices/{voice_id}/token 语音令牌 失效语音令牌
POST /v1.0/voice/execute 语音令牌 语音业务API(包括发现设备、查询设备、控制设备、触发场景、客需服务)
GET /v1.0/osaas/voices/{voice_id}/room/binding 全局令牌 获取第三方语音与房屋绑定详情

获取客需技能字典

接口描述

获取客需技能字典

接口地址

GET /v1.0/iot-02/third-voice-config/customer-skills

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String URL 请求唯一标识
version String URL API版本号,传1.0
industry_type String URL 行业类型: hotel(酒店行业).

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号

result参数说明

参数名 类型 说明
customer_skills Arrays 客需技能列表

result.customer_skills参数说明

参数名 类型 说明
intent String 客需技能类型,有六种:RoomSupplement(补充物品)、RoomClean(客房清洁)、RoomMaintenanceService(维修服务)、HotelRenew(续住服务)、CheckOut(退房服务)、LandryService(洗护服务)。此字段对应“客需服务”接口里的请求参数command.intent
values Arrays 物品列表(当 intent 是 RoomSupplement 或 RoomMaintenanceService 时,此字段才有意义)

result.customer_skills.values参数说明

参数名 类型 说明
key String 物品key。此字段对应“客需服务”接口里的请求参数command.value.materialKey
name String 物品名

请求示例

GET /v1.0/iot-02/third-voice-config/customer-skills?message_id=***&version=1.0&industry_type=hotel

响应成功示例

{
    "result": {
        "customer_skills": [
            {
                "intent": "RoomSupplement",
                "values": [
                    {
                        "key": "HS_pillow",
                        "name": "枕头"
                    },
                    {
                        "key": "HS_bed_sheet",
                        "name": "被单"
                    }
                ]
            },
            {
                "intent": "RoomClean"
            },
            {
                "intent": "RoomMaintenanceService",
                "values": [
                    {
                        "key": "HS_window_bracket",
                        "name": "窗户支架"
                    },
                    {
                        "key": "HS_faucet",
                        "name": "水龙头"
                    }
                ]
            },
            {
                "intent": "HotelRenew"
            },
            {
                "intent": "CheckOut"
            },
            {
                "intent": "LandryService"
            }
        ]
    },
    "success": true,
    "t": 1636681833634
}

响应失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

获取自定义问答

接口描述

获取自定义问答

接口地址

GET /v1.0/iot-02/third-voice-config/custom-qas

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String URL 请求唯一标识
version String URL API版本号,传1.0
industry_type String URL 行业类型: hotel(酒店行业).
space_id String URL 空间id
page_index int URL 页码
page_size int URL 每页数量

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号

result参数说明

参数名 类型 说明
page_index int 页码
page_size int 每页数量
total_page int 总页数
total_record int 总记录数
datas Object 自定义问答列表

result.datas参数说明

参数名 类型 说明
theme_id String 主题id
theme String 主题
questions Arrays 问题列表
answers Arrays 回答列表

请求示例

GET /v1.0/iot-02/third-voice-config/custom-qas?message_id=***&version=1.0&industry_type=hotel&space_id=***&page_index=1&page_size=10

响应成功示例

{
    "result": {
        "datas": [
            {
                "answers": [
                    "北京在哪一年举办奥运会",
                    "北京举办奥运会时间"
                ],
                "questions": [
                    "2008、2022"
                ],
                "theme": "北京举办奥运会时间",
                "theme_id": "852d9baaf6a34ec080979bc13c67d6bd"
            },
            {
                "answers": [
                    "中国发达城市有哪些",
                    "中国的发达城市",
                    "中国的发达城市有哪几个"
                ],
                "questions": [
                    "北京、上海、广州、深圳",
                    "北上广深"
                ],
                "theme": "中国发达城市",
                "theme_id": "0bd299aa0d8f4faaac746646c0f422a4"
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "total_page": 1,
        "total_record": 4
    },
    "success": true,
    "t": 1636708789597
}

响应失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

获取语音令牌

接口描述

调用该接口获取语音令牌

接口地址

GET /v1.0/voice/devices/{voice_id}/token

请求参数

参数名 类型 参数类型 说明 是否必填
voice_id String URI 语音设备唯一标识
code String URI 语音品牌编码(语音品牌入驻时分配的唯一编码)
industry_type String URI 行业类型: hotel(酒店行业).

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果

result参数说明

参数名 类型 说明
token String 语音令牌
refresh_token String 刷新令牌,用于刷新令牌
expire_time Long 过期时间,单位:秒

请求示例

GET /v1.0/voice/devices/***************/token?code=***********&industry_type=hotel

响应成功示例

{ 
  "result": { 
    "token"::"********************************",
    "refresh_token":"********************************",
    "expire_time":7200
  }, 
  "success": true, 
  "t": 1592899848757 
}

响应失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

刷新语音令牌

接口描述

        出于安全考虑,当前每个 OAuth token 的有效期为两小时,过期以后需要使用 refresh_token 来换取新的令牌。
说明:access_token 有时间限制,无次数限制;而 refresh_token 无时间限制,但是只能生效一次。

接口地址

GET /v1.0/token/{refresh_token}

请求参数

参数名 类型 参数类型 说明 必填
refresh_token String URI 刷新令牌

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 令牌信息

result

参数名 类型 说明
access_token String 访问令牌凭证
expire_time Integer 有效时间,单位:s
refresh_token String 刷新令牌

请求示例

GET /v1.0/token/************

返回示例

{ 
  "result": { 
    "token"::"********************************",
    "refresh_token":"********************************",
    "expire_time":7200
  }, 
  "success": true, 
  "t": 1592899848757 
}

失效语音令牌

接口描述

调用该接口失效语音令牌

接口地址

DELETE /v1.0/voice/devices/{voice_id}/token

请求参数

参数名 类型 参数类型 说明 是否必填
voice_id String URI 语音设备唯一标识码
code String URI 语音品牌编码(语音品牌入驻时分配的唯一编码)
industry_type String URI 行业类型,酒店行业:hotel.

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Boolean 操作结果

请求示例

DELETE /v1.0/voice/devices/****************/token?code=**********&industry_type=hotel

响应成功示例

{ 
  "result": true, 
  "success": true, 
  "t": 1592899848757 
}

响应失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

发现设备

接口描述

调用该接口发现设备

接口地址

POST /v1.0/voice/execute

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String BODY 请求唯一标识
version String BODY API版本号,传1.0
command Object BODY 命令

command参数说明

参数名 类型 参数类型 说明 是否必填
interface String BODY 接⼝名称:Tuya.Voice.Platform.Discovery
intent String BODY 意图: Discover

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号
command Object 命令

result参数说明

参数名 类型 说明
devices Arrays 设备列表
scenes Arrays 场景列表
space_ids Arrays 空间id列表

result.devices参数说明

参数名 类型 说明
category String 语音品类
device_name String 设备名称
device_alias_list Arrays 设备别名
position String 位置(非必须返回,无则为null)
device_id String 设备唯一标识
supported_intents Arrays 支持的语音意图列表

result.scenes参数说明

参数名 类型 说明
scene_id String 场景唯一标识
scene_name String 场景名称
supported_intents Arrays 支持的语音意图列表

请求示例

POST /v1.0/voice/execute
{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Discovery", 
    "intent": "Discover"
  }
}

响应成功示例

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Discovery", 
    "intent": "Discover" 
  }, 
  "result": { 
    "devices":[ 
      { 
        "device_id": "************", 
        "category": "light", 
        "device_alias_list": ["alias1","alias2"],
        "device_name": "bedroom light",
        "position": "Test",
        "supported_intents": [ 
            "TurnOn", 
            "TurnOff" 
        ] 
      } 
    ],
    "scenes": [
      {
        "scene_id": "SCENE#qojnjY2Tc******",
        "scene_name": "All lights turn off", 
        "supported_intents": [ 
          "TurnOn" 
        ]
      },
      {
        "scene_id": "SCENE#vZyS8yfh8******",
        "scene_name": "All lights turn on",
        "supported_intents": [ 
          "TurnOn"
        ]
      }
    ],
    "space_ids":["123***","456***"] 
  } 
}

响应失败示例

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Discovery", 
    "intent": "Discover" 
  }
}

查询设备

接口描述

调用该接口查询设备

接口地址

POST /v1.0/voice/execute

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String BODY 请求唯一标识
version String BODY API版本号,传1.0
command Object BODY 命令
endpoint Object BODY 设备

command参数说明

参数名 类型 参数类型 说明 是否必填
interface String BODY 接口名称:Tuya.Voice.Platform.Query
intent String BODY 意图: Query

endpoint参数说明

参数名 类型 参数类型 说明 是否必填
device_id String BODY 设备唯一标识

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号
command Object 命令
endpoint Object 设备.

result参数说明

参数名 类型 说明
properties Arrays 属性列表

result.properties参数说明

参数名 类型 说明
name String 属性名称
value Object 属性值

endpoint参数说明

参数名 类型 说明
device_id String 设备唯一标识

请求示例

POST /v1.0/voice/execute
{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Query", 
    "intent": "Query",
  },
  "endpoint": { 
    "device_id": "******" 
  } 
}

响应成功示例

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Query", 
    "intent": "Query" 
  },
  "endpoint": { 
    "device_id": "******" 
  }, 
  "result": { 
    "properties":[ 
      { 
        "name":"powerstate", // Power status. 
        "value":"on" 
      }, 
      { 
        "name":"color", // Color (HSV). 
        "value":{ 
          "h":350, 
          "s":40, 
          "v":40 
        } 
      }, 
      { 
        "name":"colorTemperature" // Color temperature (Kelvin). 
        "value":5000 
      }, 
      { 
        "name":"temperature", 
        "value":27 // Temperature (Celsius). 
      } 
    ] 
  } 
}

响应失败示例

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Query", 
    "intent": "Query" 
  },
  "endpoint": { 
    "device_id": "******" 
  }
}

控制设备

接口描述

调用该接口控制设备

接口地址

POST /v1.0/voice/execute

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String BODY 请求唯一标识
version String BODY API版本号,传1.0
command Object BODY 命令
endpoint Object BODY 设备

command参数说明

参数名 类型 参数类型 说明 是否必填
interface String BODY 接口名称:Tuya.Voice.Platform.Control
intent String BODY 意图
value Object BODY 命令值

endpoint参数说明

参数名 类型 参数类型 说明 是否必填
instance_id String BODY 设备唯一标识

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号
command Object 命令
endpoint Object 设备

endpoint参数说明

参数名 类型 说明
instance_id String 设备唯一标识

请求示例

POST /v1.0/voice/execute
{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "SetBrightness",
    "value": 25
  },
  "endpoint": { 
    "instance_id": "******" 
  } 
}

响应成功示例

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "SetBrightness" 
  },
  "endpoint": { 
    "instance_id": "******" 
  }
}

响应失败示例

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "SetBrightness" 
  },
  "endpoint": { 
    "instance_id": "******" 
  }
}

触发场景

接口描述

调用该接口触发场景

接口地址

POST /v1.0/voice/execute

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String BODY 请求唯一标识
version String BODY API版本号,传1.0
command Object BODY 命令
endpoint Object BODY 场景

command参数说明

参数名 类型 参数类型 说明 是否必填
interface String BODY 接口名称:Tuya.Voice.Platform.Control
intent String BODY 意图:TurnOn

endpoint参数说明

参数名 类型 参数类型 说明 是否必填
instance_id String BODY 场景唯一标识

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号
command Object 命令
endpoint Object 场景

endpoint参数说明

参数名 类型 说明
instance_id String 场景唯一标识

请求示例

POST /v1.0/voice/execute
{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "TurnOn"
  },
  "endpoint": { 
    "instance_id": "SCENE#******" 
  } 
}

响应成功示例

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "TurnOn" 
  },
  "endpoint": { 
    "instance_id": "SCENE#******" 
  }
}

响应失败示例

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "TurnOn" 
  },
  "endpoint": { 
    "instance_id": "SCENE#******" 
  }
}

客需服务

接口描述

音箱平台把入住人说的话提取一些关键词出来,然后调用本接口,为入住人呼叫客需服务

接口地址

POST /v1.0/voice/execute

请求参数

参数名 类型 参数类型 说明 是否必填
message_id String BODY 请求唯一标识
version String BODY API版本号,传1.0
command Object BODY 命令

command参数说明

参数名 类型 参数类型 说明 是否必填
interface String BODY 接⼝名称:Tuya.Voice.Platform.CustomerDemand
intent String BODY 六种客需技能类型:RoomSupplement(补充物品)、RoomClean(客房清洁)、RoomMaintenanceService(维修服务)、HotelRenew(续住服务)、CheckOut(退房服务)、LandryService(洗护服务)。此字段对应“获取客需技能字典”接口里的返回字段result.customer_skills.intent
value Object BODY 客需请求体

command.value参数说明

参数名 类型 参数类型 说明 是否必填
materialKey String BODY 物料key。此字段对应“获取客需技能字典”接口里的返回字段result.customer_skills.values.key
date String BODY 具体时间
time String BODY 时间的计量,比如五、十五
timeUnit String BODY 时间的单位,比如分钟,小时
number String BODY 物品的数量,比如一、三
numberUnit String BODY 物品的单位,比如件、个、瓶
cleanPlace String BODY 要清理的地方

六种 intent 的 value 传参说明

intent intent说明 value必传参数 value可选参数 说明
RoomSupplement 补充物品 materialKey date、time、timeUnit、number、numberUnit (date)或(time和timeUnit)二选一
1. XXX房间:{date}需要{number}{numberUnit}{materialKey}
示例:XXX房间:下午两点需要两瓶水
2. XXX房间:{time}{timeUnit}后需要{number}{numberUnit}{materialKey}
示例:XXX房间:五分钟后需要三瓶水
RoomClean 客房清洁 date、time、timeUnit、cleanPlace (date)或(time和timeUnit)二选一
1. XXX房间:{date}清洁{cleanPlace}
示例:XXX房间:下午两点清洁厕所
2. XXX房间:{time}{timeUnit}后清洁{cleanPlace}
示例:XXX房间:十分钟后清洁厕所
RoomMaintenanceService 维修服务 materialKey date、time、timeUnit、materialKey (date)或(time和timeUnit)二选一
1. XXX房间:{date}维修{materialKey}
示例:XXX房间:下午两点维修窗户支架
2. XXX房间:{time}{timeUnit}后维修{materialKey}
示例:XXX房间:十分钟后维修窗户支架
HotelRenew 续住服务 number、numberUnit XXX房间:续住{number}{numberUnit}
示例:XXX房间:续住三天
CheckOut 退房服务 date、time、timeUnit (date)或(time和timeUnit)二选一
1. XXX房间:{date}退房
示例:XXX房间:下午两点退房
2. XXX房间:{time}{timeUnit}后退房
示例:XXX房间:十分钟后退房
LandryService 洗护服务 date、time、timeUnit (date)或(time和timeUnit)二选一
1. XXX房间:{date}洗衣
示例:XXX房间:下午两点洗衣
2. XXX房间:{time}{timeUnit}后洗衣
示例:XXX房间:十分钟后洗衣

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果
message_id String 请求唯一标识
version String API版本号
command Object 命令

result参数说明

参数名 类型 说明
exist_intent Boolean 酒店是否已配置这样的客需服务
exist_material Boolean 酒店是否已配置这样的物品,当 intent 是 RoomSupplement 或 RoomMaintenanceService 时,此值才有意义
call_result Boolean 调用客需服务结果

请求示例

POST /v1.0/voice/execute
{
    "message_id": "1b7934c4219e5c4e7a540dfe834b2a49",
    "version": "1.0",
    "command": {
        "interface": "Tuya.Voice.Platform.CustomerDemand",
        "intent": "RoomSupplement",
        "value": {
            "materialKey": "HS_water",
            "time":"一",
            "timeUnit":"小时",
            "number": "三",
            "numberUnit": "瓶"
        }
    }
}

响应成功示例

{
    "command": {
        "intent": "",
        "interface": "Tuya.Voice.Platform.CustomerDemand"
    },
    "message_id": "1b7934c4219e5c4e7a540dfe834b2a49",
    "result": {
        "exist_intent": true,
        "exist_material": true,
        "call_result": true
    },
    "success": true,
    "t": 1636706858456,
    "version": "1.0"
}

响应失败示例

{
    "code": 500,
    "command": {
        "intent": "RoomSupplement",
        "interface": "Tuya.Voice.Platform.CustomerDemand"
    },
    "message_id": "1b7934c4219e5c4e7a540dfe834b2a49",
    "msg": "system error,please contact the admin",
    "success": false,
    "t": 1636707193825,
    "version": "1.0"
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参见全局错误码。

错误码 说明
500 系统错误

获取第三方语音设备与房屋绑定详情

接口描述

调用该接口获取第三方语音设备与房屋绑定详情

接口地址

GET /v1.0/osaas/voices/{voice_id}/room/binding

请求参数

参数名 类型 参数类型 说明 是否必需
voice_id String URI 三方语音设备唯一标识
code String URL 音箱品牌编码(音箱品牌入 驻时分配的唯一编码)

响应参数

参数名 类型 说明
code Integer 响应码(详情见错误码章节),成功时为空
success Boolean 是否成功:(true:成功,false:失败)
msg String 请求失败的信息,成功时为空
t Long 返回时间戳,13位
result Object 返回结果

result参数说明

参数名 类型 说明
room_no String 房屋编码
room_name String 房屋名称
project_name String 项目名称

请求示例

GET {url}/v1.0/osaas/voices/************/room/binding?code=******

响应成功示例

{
  "success": true,
  "t": 1566053034624,
  "result": {
    "room_no": "1101",
    "room_name": "豪华套房",
    "project_name": "*** 酒店"
  }
}

响应失败示例

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}