微信小程序图片违规检测接口使用指南
接口概述
做小程序开发的朋友都清楚，用户上传图片的内容安全是绕不开的坎——尤其是社交、电商类小程序，一旦出现违规图片，不仅影响平台口碑，还可能触碰监管红线。微信官方提供的media_check_async接口，就是帮我们解决这个问题的核心工具，接口地址是https://api.weixin.qq.com/wxa/media_check_async?access_token=ACCESS_TOKEN，主打异步检测图片中的违规内容，像色情、暴力、广告这些风险都能精准识别。
这个接口在实际软件开发中特别实用，比如用户上传头像、商品配图时，我们可以实时调用它做前置检测，从源头规避违规风险。不过要注意，它是异步接口，提交检测后需要通过消息推送获取结果，这一点在开发架构设计时就得提前考虑到。
使用步骤
1. 获取Access Token
调用任何微信接口，Access Token都是第一道“通行证”，media_check_async也不例外。在小程序开发中，我们通常会写一个单独的工具函数来获取和缓存它，避免重复请求浪费资源。这里要用到小程序的AppID和AppSecret，这两个信息在微信公众平台的开发设置里就能找到，记得妥善保管，千万别泄露到前端代码里。
// 获取access_token
const getAccessToken = async () => {
const appId = '你的小程序AppID';
const appSecret = '你的小程序AppSecret';
const response = await fetch(`https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`);
const data = await response.json();
if (data.access_token) {
return data.access_token;
} else {
throw new Error('获取access_token失败: ' + data.errmsg);
}
};2. 调用图片检测接口
拿到Access Token后，就能正式调用检测接口了。这里有几个关键参数要注意：media_url必须是公网可访问的图片地址，开发时可以先把用户上传的图片存到云存储或自己的服务器，再拿存储后的URL来检测;scene参数要根据实际场景选，比如用户资料上传选1，评论区图片选2，选对场景能提高检测准确率。
另外，小程序开发中如果涉及用户相关操作，建议带上openid参数，这样后续出现违规时能精准定位到具体用户，方便后续处理。下面的代码是服务端调用的示例，实际开发中绝对不能在小程序端直接调用，否则会暴露Access Token。
// 检测图片是否违规
const checkImage = async (accessToken, mediaUrl) => {
const url = `https://api.weixin.qq.com/wxa/media_check_async?access_token=${accessToken}`;
const requestBody = {
media_url: mediaUrl, // 要检测的图片URL
media_type: 1, // 1表示图片
version: 2, // 接口版本号，建议使用2
scene: 1, // 场景枚举值（1 资料；2 评论；3 论坛；4 社交日志）
openid: '用户openid' // 可选，用户的openid
};
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(requestBody)
});
const result = await response.json();
if (result.errcode === 0) {
console.log('检测任务提交成功，trace_id:', result.trace_id);
return result.trace_id; // 返回追踪ID，用于后续查询结果
} else {
throw new Error('检测任务提交失败: ' + result.errmsg);
}
};3. 处理检测结果
因为是异步接口，提交检测后不会立刻返回结果，微信会通过事件推送的方式把结果发送到我们配置的服务器地址。这一步是小程序开发中的关键环节，需要在微信公众平台的“开发-接口设置”里配置消息推送URL，同时要做好服务器的验证工作，确保能正确接收微信的推送消息。
收到推送后，我们可以通过trace_id和之前提交的检测任务关联起来，然后根据suggest字段处理不同情况：pass表示正常，可以放行;risky表示违规，要立即拦截并提示用户;review表示疑似违规，建议做人工复核。
// 处理微信服务器推送的检测结果
const handleCheckResult = (requestBody) => {
// 解析推送的数据
const { ToUserName, FromUserName, CreateTime, MsgType, Event, trace_id, result } = requestBody;
if (Event === 'wxa_media_check') {
// 根据trace_id匹配之前的检测请求
console.log(`图片检测完成，trace_id: ${trace_id}`);
if (result.suggest === 'risky') {
console.log('图片违规，原因:', result.label);
// 处理违规图片
} else if (result.suggest === 'pass') {
console.log('图片正常');
// 处理正常图片
} else {
console.log('图片疑似违规，需要人工审核');
// 处理疑似违规图片
}
}
};
class WeChatMediaChecker {
constructor(appId, appSecret) {
this.appId = appId;
this.appSecret = appSecret;
this.accessToken = null;
}
// 获取access_token
async getAccessToken() {
if (this.accessToken) {
return this.accessToken;
}
const response = await fetch(`https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${this.appId}&secret=${this.appSecret}`);
const data = await response.json();
if (data.access_token) {
this.accessToken = data.access_token;
// 设置token过期时间（微信token有效期为2小时）
setTimeout(() => {
this.accessToken = null;
}, 7100 * 1000); // 提前100秒刷新
return this.accessToken;
} else {
throw new Error('获取access_token失败: ' + data.errmsg);
}
}
// 检测图片
async checkImage(mediaUrl, openid = null) {
try {
const accessToken = await this.getAccessToken();
const requestBody = {
media_url: mediaUrl,
media_type: 1,
version: 2,
scene: 1
};
if (openid) {
requestBody.openid = openid;
}
const response = await fetch(`https://api.weixin.qq.com/wxa/media_check_async?access_token=${accessToken}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(requestBody)
});
const result = await response.json();
if (result.errcode === 0) {
console.log('图片检测任务提交成功，trace_id:', result.trace_id);
return {
success: true,
trace_id: result.trace_id
};
} else {
console.error('图片检测任务提交失败:', result.errmsg);
return {
success: false,
error: result.errmsg
};
}
} catch (error) {
console.error('检测图片时发生错误:', error);
return {
success: false,
error: error.message
};
}
}
// 处理检测结果
handleCheckResult(eventData) {
const { trace_id, result } = eventData;
console.log(`收到图片检测结果，trace_id: ${trace_id}`);
// 根据检测结果处理
switch (result.suggest) {
case 'pass':
console.log('图片正常');
// 执行正常图片的处理逻辑
break;
case 'risky':
console.log('图片违规，标签:', result.label);
// 执行违规图片的处理逻辑
break;
case 'review':
console.log('图片需要人工审核');
// 执行疑似违规图片的处理逻辑
break;
default:
console.log('未知的检测结果');
}
return {
trace_id,
suggest: result.suggest,
label: result.label
};
}
}
// 使用示例
const checker = new WeChatMediaChecker('你的AppID', '你的AppSecret');
// 提交图片检测
const mediaUrl = 'https://example.com/image.jpg';
checker.checkImage(mediaUrl, '用户openid')
.then(result => {
if (result.success) {
console.log('检测任务已提交，trace_id:', result.trace_id);
} else {
console.error('提交检测失败:', result.error);
}
});
// 在服务器接收消息推送的部分
app.post('/wechat-callback', (req, res) => {
// 处理微信服务器推送的消息
const message = req.body;
if (message.MsgType === 'event' && message.Event === 'wxa_media_check') {
// 处理图片检测结果
const checkResult = checker.handleCheckResult(message);
// 根据检测结果更新数据库或执行其他操作
updateImageStatus(checkResult.trace_id, checkResult.suggest, checkResult.label);
}
// 返回success表示接收成功
res.send('success');
});注意事项
接口频率限制：微信对该接口有明确的调用频率限制，不同资质的小程序额度不同，开发时要做好频率控制，避免触发限制导致接口不可用。建议在服务端加一层请求队列，对高频请求做缓冲处理。
图片参数要求：媒体URL必须是公网可访问的，本地开发环境的图片地址无法检测;支持PNG、JPEG、GIF等常见格式，大小不能超过10MB，超出会直接返回错误。小程序开发中可以在前端先做图片压缩，再上传检测。
检测结果解读：suggest字段是核心判断依据，pass代表正常，risky代表违规，review代表疑似违规。label字段会给出具体的违规类型，比如1是广告、2是色情，开发时可以根据这些标签做更精细化的提示。
异步机制适配：由于是异步接口，从提交检测到收到结果有一定延迟，开发时要做好用户引导，比如显示“检测中”的提示，避免用户重复操作。同时要做好异常处理，防止因网络问题导致结果丢失。
安全防护要点：Access Token、AppSecret等敏感信息必须放在服务端，绝对不能暴露到小程序前端代码;消息推送接口要做好签名验证，防止被恶意伪造请求，确保检测结果的真实性。
总的来说，media_check_async接口是小程序开发中保障图片内容安全的核心工具，只要把Token获取、任务提交、结果处理这几个环节的逻辑理清楚，再结合实际业务场景做适配，就能轻松实现图片违规检测的功能，为小程序的合规运营保驾护航。
冀公网安备