微信 API 消息模块：发送视频消息的流程与优化点

正文

在微信机器人 的消息处理能力中，发送视频消息 是一个非常典型的多媒体场景。无论是做微信自动化 通知、群内视频同步，还是客服资料推送，最终都要通过微信 API 把视频送达指定好友或群聊。本文结合 WTAPI 微信机器人接口 的 发送视频消息 接口（postVideo），梳理一下对接思路。

接口属于 微信个人号二次开发 的消息模块，采用标准的 HTTP POST 方式调用，请求地址为 /finder/v2/api/message/postVideo。

入参方面，核心有五个字段：

appId：设备实例 ID，登录成功后获取；
toWxid：接收方 ID，好友填 wxid，群聊填 chatroom ID；
videoUrl：视频文件的公网直链；
thumbUrl：视频封面缩略图链接；
videoDuration：视频时长，单位是秒。

调用示例

java 复制代码

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://wx.chuapi.com/finder/v2/api/message/postVideo")
   .header("X-finder-TOKEN", "")
   .header("Authorization", "Bearer eyJhbGciOiJIUzUxMiJ9.eyJsb2dpbl91c2VyX2tleSI6IjAxNmM2ZDQ5LWIxNWMtNGRjMy05YzQzLWZmYzZmNDhhMTg3MyJ9.1JWq9ntjam20_XDlSbklWTxbV-vg-F_dY1LYVX05BndRAuaJbv3iSwoDY-BuMwe1sdKxDXtDTMWJgXNMff4nOg")
   .header("Content-Type", "application/json")
   .body("{\n    \"appId\": \"wx_e2PiMSX8ySDV6tQGroCDc\",\n    \"toWxid\": \"wxid_tyyu4v9ykz3712\",\n    \"videoUrl\": \"https://scrm-1308498490.cos.ap-shanghai.myqcloud.com/1/41734f00f3803ca1cd8f5ad6d5f8d559.mp4?q-sign-algorithm=sha1&q-ak=AKIDmOkqfDUUDfqjMincBSSAbleGaeQv96mB&q-sign-time=1724227372;2588140972&q-key-time=1724227372;2588140972&q-header-list=&q-url-param-list=&q-signature=4e18eb97ab165f27afe0444516e54204f506c7e1\",\n    \"thumbUrl\": \"https://scrm-1308498490.cos.ap-shanghai.myqcloud.com/1/logo.jpg?q-sign-algorithm=sha1&q-ak=AKIDmOkqfDUUDfqjMincBSSAbleGaeQv96mB&q-sign-time=1724227462;2588141062&q-key-time=1724227462;2588141062&q-header-list=&q-url-param-list=&q-signature=0bc8b973567d2672e5eaada1b5d466e23ce6b750\",\n    \"videoDuration\": 10\n}")
   .asString();

这里有几个容易踩坑的地方。第一，视频和缩略图链接必须是公网可访问的直链 ，建议放在对象存储上，避免鉴权或过期问题。第二，缩略图不能省略 ，微信视频消息的展示强依赖封面图，缺失会导致消息显示异常。第三，时长单位是秒而不是毫秒，对接时要注意单位换算。

接口成功返回后，除了 msgId、newMsgId 这类消息标识，还会带回一组比较关键的 CDN 信息 ，包括 aesKey、fileId、length、cdnThumbUrl 等。

这组 CDN 字段的价值在于重复发送优化 ：如果同一个视频要发给多个对象，第二次起就不必重新上传视频文件，而是可以利用首次返回的 CDN 信息拼装 XML，直接调用转发视频接口 完成下发，能明显缩短发送时间。这在微信机器人做多对象、批量视频推送时是很实用的性能优化手段。

另外需要注意发送频率 。高频调用微信接口容易触发风控，实际项目中建议加入发送间隔、失败重试和异常码处理逻辑，保证账号长期稳定。

小结

整体来看，发送视频消息 接口本身入参不复杂，真正的重点在于：保证视频与缩略图链接可用、正确处理时长单位，以及利用返回的 CDN 信息做二次转发优化。把这几点处理好，微信个人号二次开发中的多媒体消息链路就基本打通了。