W70A/W70D 云喇叭 API

本 API 适用于 W70A/W70D 云喇叭设备。设备通过硬件云 APIv2 接入，开发者使用 app_id、app_secret 和设备序列号完成注册、语音播报、循环播报、播放状态查询、语音参数设置、上电播报、定时播报、设备信息查询、OTA 升级和解绑。W70A 和 W70D 使用 W70AIDF 固件能力，业务接口一致，主要差异是外壳和指示灯硬件。W70A/D 使用离线 TTS 芯片合成，基础播报接口兼容云喇叭常用字段，但数字读法、缓存刷新、分段步长等高级合成参数不会改变离线芯片合成效果。

app_id 和 app_secret 请登录 https://wdev.wmj.com.cn 获取。

点击下面的序号展开。

1.注册设备

简要描述

将 W70A/W70D 和 app_id、app_secret 绑定。注册成功后才能调用功能接口。

请求URL

https://wdev.wmj.com.cn/deviceApi/register

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
app_id	是	string	平台分配	硬件云 app_id
app_secret	是	string	平台分配	硬件云 app_secret
device_sn	是	string	W70A 或 W70D 设备序列号	设备序列号

返回示例

{
  "code": 0,
  "msg": "注册成功"
}

{
  "code": 1005,
  "msg": "设备已注册"
}

2.公共请求结构

简要描述

除注册、解绑外，功能接口统一调用发送指令接口，通过 data.cmd_type 区分具体功能。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

基础参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "play",
    "info": {}
  }
}

参数名	必选	类型	取值范围 / 格式	说明
app_id	是	string	平台分配	硬件云 app_id
app_secret	是	string	平台分配	硬件云 app_secret
device_sn	是	string	W70A 或 W70D 设备序列号	设备序列号
type	否	int	固定传 `1`	请求类型
data.cmd_type	是	string	本文档列出的命令名	命令类型
data.info	否	object	JSON 对象	命令参数

通用返回

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "msg_id": 1,
    "type": 1,
    "cmd": "play",
    "info": {
      "err_code": 0,
      "code": 0,
      "msg": ""
    }
  }
}

参数名	类型	说明
code	int	平台接口调用错误码，0 表示平台已受理
data.info.code	int	设备业务错误码，0 表示成功
data.info.err_code	int	兼容错误码，0 表示成功
data.info.msg	string	设备返回消息

3.播放文本语音

简要描述

让设备通过离线 TTS 芯片播放一段文本，适合收款提醒、通知播报、告警播报等场景。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "play",
    "info": {
      "tts": "欢迎使用云喇叭",
      "volume": 5,
      "speaker": "prompt_female_high",
      "speed": 1.0
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`play`，兼容 `play_adpcm`	-	文本播放命令
data.info.tts	是	string	建议 1-2048 字	-	播放文本，兼容字段 `text`
data.info.volume	否	int	`0-9`，也兼容 `10-100` 自动换算	设备默认	本次播放音量；0 或不传表示使用设备默认音量
data.info.speaker	否	string/int	`prompt_female_high` / `prompt_kunkun` / `0` / `1`	设备默认	离线芯片发音人，女声映射为 0，男声映射为 1
data.info.speed	否	number	`0-9` 或 `0.1-2.0` 倍率	设备默认	离线芯片语速，倍率会换算到 0-9 档

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd": "play",
    "info": {
      "code": 0,
      "err_code": 0,
      "msg": "TTS started",
      "volume_arg": 5
    }
  }
}

4.查询播放状态

简要描述

查询设备当前播放、循环播放和语音链路状态。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "get_play_status",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd": "get_play_status",
    "info": {
      "code": 0,
      "err_code": 0,
      "msg": "",
      "is_playing": false,
      "is_loop_playing": false,
      "is_live_talk": false,
      "volume": 5,
      "last_error": ""
    }
  }
}

5.循环播报

简要描述

让设备按固定间隔循环播报文本。适用于持续提醒、异常告警等场景。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

开始循环播报

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "loop_play",
    "info": {
      "tts": "设备异常，请及时处理",
      "interval": 10,
      "volume": 5,
      "speaker": "prompt_female_high",
      "speed": 1.0
    }
  }
}

停止循环播报

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "loop_stop",
    "info": {}
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`loop_play` / `loop_stop`	-	循环播报命令
data.info.tts	loop_play 必填	string	建议 1-2048 字	-	循环播报文本，兼容字段 `text`
data.info.interval	否	int	秒，建议大于单次语音时长	5	循环间隔
data.info.volume	否	int	`0-9`，也兼容 `10-100` 自动换算	设备默认	播报音量
data.info.speaker	否	string/int	`prompt_female_high` / `prompt_kunkun` / `0` / `1`	设备默认	离线芯片发音人
data.info.speed	否	number	`0-9` 或 `0.1-2.0` 倍率	设备默认	离线芯片语速

6.停止当前播放

简要描述

停止当前正在播放的语音。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "stop_play",
    "info": {}
  }
}

7.设置语音和上电播报

简要描述

设置设备默认音量、发音人、语速、语调和上电播报。设置后会持久保存。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "setting",
    "info": {
      "volume": 5,
      "volume_percent": 50,
      "speaker": 4,
      "speed": 5,
      "tone": 5,
      "pwr_on_enabled": 1,
      "pwr_on_text": "欢迎使用云喇叭",
      "pwr_on_delay": 3,
      "pwr_on_volume": 5,
      "pwr_on_repeat": 1
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`setting`	-	设置命令
data.info.volume	否	int	`0-9`	设备当前值	默认音量档位
data.info.volume_percent	否	int	`0-100`	设备当前值	默认音量百分比，设备会换算到离线芯片音量档位
data.info.speaker	否	int	`0` / `1`	设备当前值	默认发音人编号，0 女声，1 男声
data.info.speed	否	int	`0-9`	设备当前值	离线芯片默认语速
data.info.tone	否	int	`0-9`	设备当前值	默认语调
data.info.pwr_on_enabled	否	int/bool	`0` / `1`	设备当前值	是否启用上电播报
data.info.pwr_on_text	否	string	建议 1-540 字节	设备当前值	上电播报文本；超长会返回 413
data.info.pwr_on_delay	否	int	`0-3600` 秒	0	上电后延迟播报时间
data.info.pwr_on_volume	否	int	`1-10` 或 `0-100`	设备当前值	上电播报音量
data.info.pwr_on_repeat	否	int	`1-10`	1	上电播报重复次数

8.查询设备信息

简要描述

查询设备版本、网络状态、语音参数、上电播报、播放状态、定时播报和 OTA 状态。公开文档不展示设备接入密钥、管理密码、默认云接入参数等内部字段。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "getdevinfo",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd": "getdevinfo",
    "info": {
      "sw_ver": "70.4.33",
      "hw_ver": "1.0.0",
      "project": "W70A_CPP / W70D_CPP",
      "net_type": "wifi",
      "iccid": "{{ssid_or_empty}}",
      "imei": "AA:BB:CC:DD:EE:FF",
      "speaker": 4,
      "volume": 5,
      "volume_percent": 50,
      "speed": 5,
      "tone": 5,
      "pwr_on_enabled": 1,
      "pwr_on_text": "欢迎使用云喇叭",
      "pwr_on_delay": 3,
      "pwr_on_volume": 5,
      "pwr_on_repeat": 1,
      "is_playing": false,
      "is_loop_playing": false,
      "schedule_enabled_count": 1,
      "schedule_total_count": 20,
      "time_synced": true,
      "free_heap": 120000,
      "code": 0,
      "err_code": 0,
      "msg": ""
    }
  }
}

返回字段说明

字段	类型	说明
sw_ver	string	软件版本
hw_ver	string	硬件版本
project	string	项目标识
net_type	string	网络类型
iccid	string	WiFi SSID 或内部网络标识
imei	string	设备网络 MAC 标识
speaker	int	当前默认发音人编号
volume	int	当前默认音量兼容档位
volume_percent	int	当前默认音量百分比
speed	int	当前默认语速
tone	int	当前默认语调
pwr_on_enabled	int	是否启用上电播报
pwr_on_text	string	上电播报文本
pwr_on_delay	int	上电播报延迟
pwr_on_volume	int	上电播报音量
pwr_on_repeat	int	上电播报重复次数
is_playing	bool	当前是否正在播放
is_loop_playing	bool	当前是否循环播放
schedule_enabled_count	int	已启用定时播报数量
schedule_total_count	int	定时播报槽位总数
time_synced	bool	设备时间是否已同步
free_heap	int	设备剩余内存，单位字节

9.设置定时播报

简要描述

设置单个定时播报任务。设备最多支持 20 组任务，时间以设备本地时区为准。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_tts_schedule",
    "info": {
      "index": 0,
      "enabled": true,
      "hour": 9,
      "minute": 30,
      "weekdays": 62,
      "tts_text": "请及时处理待办事项",
      "speaker": "prompt_female_high",
      "speed": 1.0,
      "repeat_count": 3
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`set_tts_schedule`	-	设置单个任务
data.info.index	是	int	`0-19`	-	定时任务序号
data.info.enabled	否	bool	`true` / `false`	false	是否启用
data.info.hour	否	int	`0-23`	0	播报小时
data.info.minute	否	int	`0-59`	0	播报分钟
data.info.weekdays	否	int	`1-127`	127	星期掩码，bit0 周日，bit1 周一，依次到 bit6 周六；127 表示每天
data.info.tts_text	否	string	建议 1-2048 字	空	播报文本，兼容字段 `text`
data.info.speaker	否	string/int	`prompt_female_high` / `prompt_kunkun` / `0` / `1`	`prompt_female_high`	离线芯片发音人
data.info.speed	否	number	`0-9` 或 `0.1-2.0` 倍率	1.0	离线芯片语速
data.info.repeat_count	否	int	`1-10`	3	触发后重复播报次数

weekdays 示例

取值	含义
127	每天
62	周一到周五
65	周六和周日

10.批量设置定时播报

简要描述

一次性设置多组定时播报任务。schedules 数组最多 20 项，数组下标对应任务序号。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_tts_schedules",
    "info": {
      "schedules": [
        {
          "index": 0,
          "enabled": true,
          "hour": 9,
          "minute": 0,
          "weekdays": 127,
          "tts_text": "早上好",
          "speaker": "prompt_female_high",
          "speed": 1.0,
          "repeat_count": 1
        }
      ]
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`set_tts_schedules`	批量设置任务
data.info.schedules	是	array	最多 20 项	定时任务数组

11.查询定时播报

简要描述

查询设备当前保存的定时播报任务、设备当前时间和时间同步状态。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "get_tts_schedules",
    "info": {}
  }
}

返回字段说明

字段	类型	说明
schedules	array	定时任务列表
current_time	string	设备当前时间，格式 `YYYY-MM-DD HH:mm:ss`
weekday	int	当前星期，0 周日，1 周一，依次到 6 周六
time_synced	bool	是否已同步网络时间

12.清除定时播报

简要描述

清除单个或全部定时播报任务。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

清除单个任务

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "clear_tts_schedule",
    "info": {
      "index": 0
    }
  }
}

清除全部任务

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "clear_all_tts_schedules",
    "info": {}
  }
}

13.音频资源升级

简要描述

检查并更新设备本地音频资源。一般仅在设备提示音资源需要升级时使用。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "audio_ota",
    "info": {
      "force": false
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`audio_ota`	音频资源升级命令
data.info.force	否	bool	`true` / `false`	是否强制检查更新

14.重启和恢复

重启设备

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "restart",
    "info": {}
  }
}

恢复设备配置

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "reset",
    "info": {}
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`restart` / `reset`	重启设备或恢复设备配置

15.OTA 升级

简要描述

让设备下载指定 OTA 固件并升级。OTA 文件 URL 需要设备网络可直接访问。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ota",
    "info": {
      "hw_ver": "1.0.0",
      "sw_ver": "70.4.33",
      "url": "https://example.com/ota/W70A_CPP_V70.4.34.bin"
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`set_ota`	OTA 命令
data.info.hw_ver	是	string	设备硬件版本	必须和设备硬件版本一致
data.info.sw_ver	是	string	大于当前版本	目标软件版本
data.info.url	是	string	HTTP/HTTPS URL	OTA 固件地址，请使用平台发布的正式升级包

16.回调与上报

简要描述

设备在上线、指令执行完成、播放状态变化或门磁/按键状态变化时，通过硬件云返回或上报数据。业务系统应按 device_sn、cmd、msg_id 做幂等处理。

播放完成上报示例

{
  "device_sn": "{{device_sn}}",
  "type": 2,
  "cmd_type": "tts_complete",
  "info": {
    "status": "success",
    "timestamp": 123456
  }
}

状态上报示例

{
  "device_sn": "{{device_sn}}",
  "type": 2,
  "cmd_type": "exitopened",
  "info": {
    "status": 0
  }
}

17.查询在线状态

请求URL

https://wdev.wmj.com.cn/deviceApi/getOnLine

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "data": {
    "on_line": 1
  },
  "msg": "查询成功"
}

18.常见问题

播放没有声音

先调用 getdevinfo 或 get_play_status 确认音量不是 0，再调用 setting 设置 volume 或 volume_percent。W70A/D 使用离线芯片合成，音量最终会换算到芯片支持的 0-9 档。

数字读法不符合预期

W70A/D 为离线芯片合成，number_mode、refresh_cache、num_step 等高级合成参数仅做接口兼容，不保证改变离线芯片读法。需要严格控制数字读法时，建议业务侧把播报文本处理成期望读法后下发。

定时播报没有触发

先调用 get_tts_schedules 查看 time_synced 是否为 true，并确认 weekdays、hour、minute 与设备当前时间匹配。

19.解绑设备

简要描述

解除设备与 app_id、app_secret 的绑定。解绑后该应用不能继续控制设备。

请求URL

https://wdev.wmj.com.cn/deviceApi/logout

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "msg": "解绑成功"
}

更新日志

日期	内容
2026-06-25	按 W70AIDF 离线 TTS 芯片能力重整 W70A/W70D APIv2 文档，移除默认云接入配置和管理密码类字段，仅保留公开业务接口

作者：极客师傅创建时间：2026-06-25 01:29
最后编辑：极客师傅更新时间：2026-06-25 01:53

上一篇： W70B/W70R 云喇叭 API
下一篇： W70G 云喇叭 API