
小程序内容安全的核心,是在服务端对由用户生产、且会被其他用户访问的内容调用官方检测接口,并正确处理三类结果:pass 放行、review 转人工、risky 拒绝。检测接口必须在服务器端调用,不可放在小程序前端;文本走同步接口 msgSecCheck,图片与音频走异步接口 mediaCheckAsync。本文按「调用主体 → 文本请求字段 → 文本返回结构 → 场景与标签 → 频率与错误码 → 异步检测链路 → 审核闭环」的接口契约顺序说明,字段、枚举与阈值均以微信开放文档当前口径为准。
一、接口定位与调用主体约束
内容安全类接口属于服务端接口。官方明确规定:接口应在服务器端调用,不可在前端(小程序、网页、APP 等)直接调用。原因是调用需要携带 access_token 等凭据,若下发到前端会造成凭据泄露。小程序端只负责把待检测内容提交给自有服务端或云函数,由服务端完成检测并把结果回传。
| 接口 | 英文名 | 检测对象 | 调用方式 | 结果形态 |
|---|---|---|---|---|
| 文本内容安全识别 | msgSecCheck | 一段文本,上限 2500 字 | 同步 HTTPS POST / 云调用 | 请求内即时返回 suggest 与 label |
| 媒体内容安全检测 | mediaCheckAsync | 图片或音频文件,单个不超过 10M | 异步 HTTPS POST / 云调用 | 返回 trace_id,结果在 30 分钟内推送 |
云调用方法名分别为 security.msgSecCheck 与 security.mediaCheckAsync,出入参与 HTTPS 调用相同。两个接口均支持第三方平台代商家调用,所属权限集 id 为 18,服务商取得权限集授权后可用 authorizer_access_token 调用。
二、文本检测请求字段
msgSecCheck 的请求分为查询参数与请求体两部分。access_token 放在查询参数中,其余字段放在请求体。省略必填字段、字段类型不符或超出字数上限,均会导致接口返回错误而非检测结果。
| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| access_token | Query | string | 是 | 接口调用凭证,可用 access_token 或 authorizer_access_token |
| content | Body | string | 是 | 待检测文本,字数上限 2500,需 UTF-8 编码 |
| version | Body | number | 是 | 接口版本号,2.0 版本固定值 2 |
| scene | Body | number | 是 | 场景枚举值,见第四节 |
| openid | Body | string | 是 | 用户 openid,用户需在近两小时访问过小程序 |
| title | Body | string | 否 | 文本标题,需 UTF-8 编码 |
| nickname | Body | string | 否 | 用户昵称,需 UTF-8 编码 |
| signature | Body | string | 否 | 个性签名,仅在 scene=1 资料场景有效 |
接口地址为 POST https://api.weixin.qq.com/wxa/msg_sec_check?access_token=ACCESS_TOKEN ,并支持服务通信二次加密与签名。openid 的时效要求常被忽略:若用户未在近两小时访问小程序,即便 openid 本身合法,也会返回 61010(用户访问记录超时)。

三、文本检测返回结构
返回体由综合结果 result、详细结果 detail 与请求标识 trace_id 构成。result.suggest 是最直接的处置依据;detail 数组列出各策略的判定明细,用于定位具体命中项。trace_id 是唯一请求标识,联调与申诉时应一并留存。
| 返回字段 | 类型 | 说明 |
|---|---|---|
| errcode | number | 错误码,为 0 表示本次调用成功 |
| errmsg | string | 错误信息 |
| result.suggest | string | 综合建议:risky、pass、review 三种值 |
| result.label | number | 综合命中标签枚举值 |
| detail | objarray | 详细检测结果数组,逐策略列出判定 |
| trace_id | string | 唯一请求标识,标记单次请求 |
| detail 子字段 | 类型 | 说明 |
|---|---|---|
| strategy | string | 策略类型,例如 content_model、keyword |
| errcode | number | 仅当该值为 0 时,该项结果有效 |
| suggest | string | 该项建议:risky、pass、review |
| label | number | 该项命中标签枚举值 |
| keyword | string | 命中的自定义关键词 |
| prob | number | 0~100,置信度,越高越可能属于当前标签 |
工程上常见的疏漏是只处理 pass 与 risky,把 review 当作 pass 放行。三类建议需要分别落到不同分支:pass 直接放行,risky 拒绝提交,review 进入人工队列。接口异常或超时同样应按 review 处理,即不放行也不直接拒绝。

四、场景值与标签枚举
scene 决定检测采用的场景策略,取值错误会返回 40129(invalid scene)。signature 字段只在 scene=1 时有效,填在其他场景不会生效。
| 类别 | 枚举 | 含义 |
|---|---|---|
| scene 场景 | 1 | 资料 |
| scene 场景 | 2 | 评论 |
| scene 场景 | 3 | 论坛 |
| scene 场景 | 4 | 社交日志 |
| label 标签 | 100 | 正常 |
| label 标签 | 10001 | 广告 |
| label 标签 | 20001 | 时政 |
| label 标签 | 20002 | 色情 |
| label 标签 | 20003 | 辱骂 |
| label 标签 | 20006 | 违法犯罪 |
| label 标签 | 20008 | 欺诈 |
| label 标签 | 20012 | 低俗 |
| label 标签 | 20013 | 版权 |
| label 标签 | 21000 | 其他 |
label 同时出现在 result 与 detail 中:result.label 是综合判定的命中标签,detail 中每一项各自带有 label 与 prob,可用于判断具体是哪一类风险、置信度多高。
五、频率限制与错误码反查
频率限制按 appId 计算。msgSecCheck 单个 appId 上限为 4000 次/分钟、2000000 次/天;未上架小程序上限为 100 次/天。mediaCheckAsync 单个 appId 上限为 2000 次/分钟、200000 次/天。超出后分别返回 44991(分钟频率)与 45009(日额度)。
| 错误码 | 错误描述 | 处理方向 |
|---|---|---|
| -1 | system error 系统繁忙 | 稍候再试 |
| 40001 | access_token 无效或不是最新获取 | 重新获取并缓存凭据,避免并发刷新互相覆盖 |
| 40003 | invalid openid | 确认 openid 来源与格式 |
| 40129 | invalid scene | 将 scene 改为 1~4 中的合法值 |
| 43002 | require POST method | 改用 POST 调用 |
| 43104 | openid 与 appid 不匹配 | 核对调用主体与 openid 所属应用 |
| 44002 | empty post data | 检查请求体是否已正确序列化并发送 |
| 44991 | 超出每分钟调用限制 | 降低峰值或做本地排队 |
| 45009 | 超出每日调用限制 | 核查异常调用来源,必要时调整业务频次 |
| 47001 | data format error | 检查 JSON 格式与必填参数是否齐全 |
| 61010 | 用户访问记录超时 | 用户需在近两小时访问过小程序 |

六、图片与音频异步检测链路
mediaCheckAsync 用于异步校验图片或音频。调用成功只表示检测请求已被接收,并不代表内容通过。接口返回 trace_id 作为任务标识,检测结果会在 30 分钟内推送到消息接收服务器,需用 trace_id 匹配异步结果。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| media_url | string | 是 | 待检测文件 URL,需保证检测服务器可下载 |
| media_type | number | 是 | 1 音频;2 图片,须与 URL 实际类型一致 |
| version | number | 是 | 接口版本号,固定值 2 |
| scene | number | 是 | 场景枚举值 1 资料、2 评论、3 论坛、4 社交日志 |
| openid | string | 是 | 用户 openid,需在近两小时访问过小程序 |
支持的图片格式包括 jpg、jpeg、png、bmp、gif(仅首帧);支持的音频格式包括 mp3、aac、ac3、wma、flac、vorbis、opus、wav。单个文件大小不超过 10M。media_type 需与 URL 对应的多媒体类型准确一致,否则会影响检测结果。
| 推送字段 | 含义 | 取值要点 |
|---|---|---|
| trace_id | 任务 ID | 与调用返回值一致,用于匹配结果 |
| errcode | 错误码 | 为 0 时结果有效;-1008 表示下载错误,检查媒体链接 |
| result.suggest | 综合建议 | risky、pass、review 三种值 |
| result.label | 命中标签 | 100 正常、20001 时政、20002 色情、20006 违法犯罪、21000 其他 |
| detail | 详细结果 | 逐策略列出,含 strategy、errcode、suggest、label |
| Event / MsgType | 事件类型 | Event 为 wxa_media_check,MsgType 为 event |
由于结果最多 30 分钟才推送,内容发布流程不应同步等待检测结果。常见做法是:提交时内容先进入待审状态,异步结果到达后按三态更新状态,并对长时间未收到结果的记录做超时兜底。
七、审核闭环与上线前自检
接口只给出机器判定,业务上仍需要完整闭环。机器判为 review 的内容进入人工队列;发布后按需抽样复查,并提供用户举报入口,举报命中后转入人工队列处理。这样即使个别判定与具体业务语境不符,也有可追溯的兜底路径。
- 检测调用全部放在服务端或云函数,前端不持有 access_token 等凭据。
- access_token 统一获取与缓存,避免多处并发刷新导致 40001。
- content 长度控制在 2500 字以内并使用 UTF-8 编码,超长内容分段送检。
- version 固定填 2,scene 按实际场景取 1~4,签名仅在 scene=1 时填写。
- openid 取自当前用户,并确保用户近两小时访问过小程序。
- result.suggest 的 pass、review、risky 三态分别有明确处理分支,异常按 review 处理。
- 异步检测以 trace_id 建立任务台账,结果到达后匹配更新,并保留超时兜底。
- 留存 trace_id、detail 与命中标签,便于联调定位与后续核查。
八、常见问题
小程序内容安全接口是什么?
指微信提供的服务端检测能力,常用的有文本内容安全识别 msgSecCheck 与媒体内容安全检测 mediaCheckAsync,分别覆盖文本与图片、音频的违法违规内容识别。
小程序内容安全检测怎么做?
由服务端调用检测接口:文本同步送入 msgSecCheck 并取得 suggest,图片或音频调用 mediaCheckAsync 后用 trace_id 接收异步结果,再按三态处置。
小程序内容安全校验不通过怎么办?
先看 result.suggest 与 detail 中的命中标签、关键词和置信度,定位具体风险点;如果判定为 review,应进入人工复核,而不是直接放行或直接拒绝。
小程序内容安全api接口怎么用?
在服务端以 POST 请求接口地址,查询参数带 access_token,请求体按字段要求填写 content、version、scene、openid 等,解析返回的 result 与 detail。
小程序内容审核api怎么调用?
可用 HTTPS 服务端调用,也可用云调用 security.msgSecCheck;两种方式出入参一致。第三方服务商取得权限集 18 授权后,可用 authorizer_access_token 代调用。
小程序内容审核是什么意思?
指对用户生产且会被其他用户看到的内容做合规检测与处置,包含机器检测、人工复核与发布后复查,避免违规内容在小程序内传播。
小程序内容安全机制包含哪些环节?
通常包含提交前检测、结果三态处置、人工复核队列、发布后抽样复查与用户举报入口,接口检测只是其中一个环节。
小程序内容审核要多久?
文本检测在请求内同步返回;图片与音频走异步检测,结果在 30 分钟内推送到消息接收服务器,因此需要按待审状态设计流程并设置超时兜底。
九、核验路径小结
内容安全配置是否完整,可以用一条可复现的核验路径判断:确认调用发生在服务端,确认必填字段与枚举值合法,确认三态结果各有处理分支,确认异步任务有 trace_id 台账与超时兜底,确认留存了 trace_id 与命中明细。上述条目对应的接口地址、字段、枚举与错误码均可按本文表格逐项对照,形成固定的上线前核对流程。
配图说明:本文部分配图使用人工智能生成合成技术制作。





