W70G 云喇叭 API

本 API 适用于 W70G 云喇叭设备。W70G 通过硬件云 APIv2 接入，开发者使用 app_id、app_secret 和设备序列号完成注册、语音播放、音量设置、定时播报、播放状态查询、缓存清理、OTA 升级和解绑。

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

点击下面的序号展开。

1.注册设备

简要描述

将 W70G 云喇叭和 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	W70G 设备序列号	设备序列号

返回示例

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

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

2.公共请求结构

简要描述

除注册、解绑外，W70G 功能接口统一调用发送指令接口，通过 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	W70G 设备序列号	设备序列号
type	否	int	固定传 `1`	请求类型
data.cmd_type	是	string	本文档列出的命令名	命令类型
data.info	否	object	JSON 对象	命令参数

通用返回

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "msg_id": 1,
    "type": 1,
    "cmd_type": "play",
    "info": {
      "code": 0,
      "err_code": 0,
      "msg": "MP3 TTS started"
    }
  }
}

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

3.播放云语音

简要描述

让 W70G 云喇叭播放一段文本。设备优先使用在线 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": "欢迎使用云喇叭",
      "speaker": "prompt_female_high",
      "speed": 5,
      "num_step": 2,
      "number_mode": "digit",
      "refresh_cache": 1,
      "buffered": 0,
      "volume": 5
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`play`，兼容 `play_tts`	-	文本播放命令
data.info.tts	是	string	1-2048 字建议	-	播放文本，兼容字段 `text`
data.info.speaker	否	string	发音人标识，例如 `prompt_female_high`	`prompt_female_high`	发音人
data.info.speed	否	number	1-9 兼容档位，或大于 0 的倍率	按设备配置	语速
data.info.num_step	否	int	正整数，建议 `2`	2	数字分段步长
data.info.number_mode	否	string	`digit` / `value`	`value`	数字读法，`digit` 按位读，`value` 按数值读
data.info.refresh_cache	否	int/bool	`0` / `1`	1	是否刷新或使用缓存
data.info.buffered	否	int/bool	`0` / `1`	0	是否缓冲后播放
data.info.volume	否	int	1-10 云喇叭音量，或 0-100 百分比	设备默认	本次播放音量

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "play",
    "info": {
      "code": 0,
      "err_code": 0,
      "msg": "MP3 TTS started"
    }
  }
}

4.播放 MP3 音频

简要描述

让 W70G 下载并播放一个 MP3 地址。音频地址需要设备 4G 网络可直接访问。

请求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_mp3",
    "info": {
      "url": "https://example.com/audio/notice.mp3",
      "volume": 5
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`play_mp3`	播放 MP3 命令
data.info.url	是	string	HTTP/HTTPS MP3 URL，建议 HTTPS	音频文件地址
data.info.volume	否	int	1-10 或 0-100	本次播放音量

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": "请及时处理当前订单",
      "loop": 3,
      "interval_sec": 5,
      "volume": 5
    }
  }
}

停止循环播报

{
  "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-512 字建议	-	播报文本，兼容字段 `text`
data.info.loop	否	int	0-100，负数按 1 处理	0	循环次数。`0` 表示按设备循环任务处理，最大 100
data.info.interval_sec	否	int	0 或正整数秒	5	每次播报间隔，兼容字段 `interval`
data.info.volume	否	int	1-10 或 0-100	设备默认	播报音量

6.停止播放

简要描述

停止当前文本、MP3、广播或循环播放任务。

请求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": {}
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`stop_play`，兼容 `stop_tts`	停止当前播放

7.查询播放状态

简要描述

查询当前播放状态、音量、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": "get_play_status",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "get_play_status",
    "info": {
      "code": 0,
      "msg": "OK",
      "state": "idle",
      "is_playing": 0,
      "is_loop_playing": 0,
      "mode": "tts",
      "stream_format": "opus",
      "sample_rate": 16000,
      "volume": 50,
      "speaker": "prompt_female_high",
      "number_mode": "digit",
      "last_error": 0
    }
  }
}

8.音量和开机播报设置

简要描述

设置设备默认音量、语速档位、音色档位、发音人和开机播报内容。

请求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,
      "speed": 5,
      "tone": 5,
      "speaker": 0,
      "pwr_on_enabled": 1,
      "pwr_on_text": "欢迎使用云喇叭",
      "pwr_on_delay": 3,
      "pwr_on_volume": 3,
      "pwr_on_repeat": 1
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	默认值	说明
data.cmd_type	是	string	`setting`	-	设置命令
data.info.volume	否	int	0-9 兼容档位，或 0-100 百分比	设备默认	默认播放音量
data.info.speed	否	int	0-9	设备默认	语速兼容档位
data.info.tone	否	int	0-9	设备默认	音色兼容档位
data.info.speaker	否	int	`0` / `1`	0	发音人兼容选项
data.info.pwr_on_enabled	否	int/bool	`0` / `1`	设备默认	是否启用开机播报
data.info.pwr_on_text	否	string	0-512 字	`欢迎使用云喇叭`	开机播报文本
data.info.pwr_on_delay	否	int	0-3600 秒	设备默认	开机后延迟播报时间
data.info.pwr_on_volume	否	int	1-10 映射到 10-100，最终限制 10-60	20	开机播报音量
data.info.pwr_on_repeat	否	int	1-10	1	开机播报重复次数

9.定时播报

简要描述

配置一组定时 TTS 播报任务。最多支持 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": 1,
      "hour": 9,
      "minute": 30,
      "weekdays": 127,
      "repeat_count": 1,
      "text": "现在开始营业",
      "speaker": "prompt_female_high",
      "number_mode": "digit"
    }
  }
}

查询定时播报

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

清除单条定时播报

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

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`set_tts_schedule` / `set_tts_schedules` / `get_tts_schedules` / `clear_tts_schedule` / `clear_all_tts_schedules`	定时播报命令
data.info.index	单条设置/清除必填	int	0-19	定时任务序号
data.info.enabled	否	int/bool	`0` / `1`	是否启用
data.info.hour	否	int	0-23	播报小时
data.info.minute	否	int	0-59	播报分钟
data.info.weekdays	否	int	0-127	星期位图，默认 127 表示每天
data.info.repeat_count	否	int	1-10	每次触发重复次数
data.info.text	否	string	0-512 字	播报文本，兼容字段 `tts_text`
data.info.speaker	否	string	发音人标识	发音人
data.info.number_mode	否	string	`digit` / `value`	数字读法

10.TTS 服务配置

简要描述

配置设备连接的 TTS 服务地址。一般无需修改，只有接入私有化 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": "set_tts_server",
    "info": {
      "ws_host": "voice.wmj.com.cn",
      "ws_port": 8180,
      "ws_path": "/ws/tts/stream",
      "http_url": "http://voice.wmj.com.cn"
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`set_tts_server`	设置 TTS 服务
data.info.ws_host	否	string	域名或 IP	WebSocket TTS 主机
data.info.ws_port	否	int	1-65535	WebSocket TTS 端口
data.info.ws_path	否	string	URL path	WebSocket TTS 路径，兼容字段 `path`
data.info.http_url	否	string	HTTP/HTTPS URL	HTTP TTS 基础地址

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": "cleanup_storage",
    "info": {}
  }
}

删除指定 TTS 缓存

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "delete_tts_cache",
    "info": {
      "text": "欢迎使用云喇叭",
      "speaker": "prompt_female_high",
      "number_mode": "digit",
      "all_variants": 1
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`cleanup_storage` / `clear_storage` / `delete_tts_cache` / `clear_tts_cache` / `reset_tts`	存储或缓存管理命令
data.info.text	删除指定缓存时必填	string	播报文本	要删除缓存对应的文本
data.info.speaker	否	string	发音人标识	发音人
data.info.number_mode	否	string	`digit` / `value`	数字读法
data.info.all_variants	否	int/bool	`0` / `1`	是否删除同文本的所有变体

12.音频资源更新

简要描述

下载并更新设备本地 MP3 缓存文件。没有传 URL 时，设备只返回当前在线 TTS/MP3 缓存状态。

请求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": {
      "url": "https://example.com/audio/play_mp3_audio.mp3"
    }
  }
}

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`audio_ota`	音频资源更新
data.info.url	否	string	HTTP/HTTPS MP3 URL，建议 HTTPS	要下载缓存的 MP3 地址

13.读取设备信息

简要描述

读取 W70G 设备信息、版本、4G 模组信息、音频配置和存储状态。

请求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": {}
  }
}

返回字段说明

字段	类型	说明
imsi	string	SIM IMSI
iccid	string	SIM ICCID
imei	string	模组 IMEI
hw	string	硬件版本
sw	string	软件版本
model	string	模组型号
fwVer	string	固件版本
project	string	项目标识
version	string	版本号
volume	int	兼容音量档位
speed	int	兼容语速档位
tone	int	兼容音色档位
speaker	int	发音人兼容选项
pwr_on_enabled	int	是否启用开机播报
pwr_on_text	string	开机播报文本
tts_ws_host	string	TTS WebSocket 主机
tts_ws_port	int	TTS WebSocket 端口
tts_ws_path	string	TTS WebSocket 路径
tts_http_url	string	TTS HTTP 地址
rssi	int	4G 信号强度
csq	int	模组 CSQ
ber	int	误码率

14.OTA 升级和重启

OTA 升级

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ota",
    "info": {
      "url": "https://example.com/ota/w70g.fota"
    }
  }
}

重启设备

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

参数说明

参数名	必选	类型	取值范围 / 格式	说明
data.cmd_type	是	string	`set_ota` / `restart`	OTA 或重启命令
data.info.url	OTA 必填	string	HTTP/HTTPS OTA 文件 URL	OTA 升级包地址

OTA 返回消息

code	msg	说明
0	OTA started, device will reboot	OTA 已开始，设备将重启
-1	OTA URL is empty 或 OTA command missing URL parameter	缺少 URL
-2	Invalid URL format	URL 格式错误
-3	Set OTA URL failed	设置 OTA URL 失败
-4	FOTA exec failed	执行升级失败
-5	Not enough storage	存储空间不足
-6	Get storage info failed	获取存储信息失败

15.回调与上报

简要描述

设备在注册上线、指令执行完成、播放状态变化或 OTA 异常时，通过硬件云返回或上报数据。业务系统应按 cmd_type 和 msg_id 做幂等处理。

指令返回示例

{
  "cmd_type": "play",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "msg_id": 1001,
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "MP3 TTS started"
  }
}

OTA 异常上报示例

{
  "cmd_type": "set_ota",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "msg_id": 0,
  "info": {
    "code": -1,
    "msg": "FOTA download error"
  }
}

业务系统要求

同一指令可能因网络重试出现重复返回，建议按 device_sn、cmd_type、msg_id 做幂等。
播放类指令返回成功表示设备已受理或开始播放，不等同于整段语音已经播放完成。
长文本建议控制单次文本长度，确需长文本时可分多次下发或使用循环播报。

16.常见问题

播放没有声音

先调用 get_play_status 查看 state、is_playing、last_error 和 volume，再确认设备 4G 网络可访问 TTS 服务或 MP3 地址。

相同文本重复播放慢

建议 refresh_cache 传 1，设备会缓存相同文本的合成结果。需要清除缓存时使用 delete_tts_cache 或 clear_tts_cache。

数字读法不符合预期

使用 number_mode=digit 按位播报数字，使用 number_mode=value 按数值播报数字。

17.解绑设备

简要描述

解除设备与 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	新增 W70G 云喇叭 APIv2 开发文档，覆盖播放、状态、音量、定时播报、TTS 服务、缓存、音频资源、设备信息、OTA 和解绑

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

上一篇： W70A/W70D 云喇叭 API
下一篇： W702/W704/W705 云喇叭API