健康检查

服务存活探测接口，用于负载均衡与可用性监控。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/ads/ping JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.version	string	服务版本号
data.time	string	服务器当前时间（探测时间）

请求示例

返回示例

{"msg":"success","code":200,"data":{"time":"2026-10-23 19:34:59","version":"1.0"}}

违禁词分类列表

返回全部违禁词分类及其默认风险等级、法律依据。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/ads/categories JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.count	integer	分类总数
data.categories	array	分类列表
data.categories[]	object	单个分类
data.categories[].code	string	分类代码，用于检测接口的 categories 参数
data.categories[].name	string	分类名称
data.categories[].level	string	默认风险等级：high / medium / low
data.categories[].law	string	法律依据

请求示例

返回示例

{"msg":"success","code":200,"data":{"count":27,"categories":[{"law":"广告法第九条第三项","code":"absolute","name":"绝对化用语","level":"high"},{"law":"广告法第十七条","code":"medical","name":"医疗/保健","level":"high"},{"law":"广告法第二十五条","code":"finance","name":"金融/投资","level":"high"}]}}

白名单数量统计

返回白名单豁免词条数量（不返回具体词条）

返回广告法检测白名单中配置的豁免词条数量。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/ads/whitelist JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.count	integer	豁免词条数

请求示例

返回示例

{"msg":"success","code":200,"data":{"count":59}}

单段文本检测

检测单段文本中的违禁词，返回命中详情、风险等级与白名单豁免情况。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/ads/check JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
text	string	是	待检测文本（去除首尾空白后不能为空，最大 10240 字符 / 10KB）
categories	array	否	限定检测分类代码数组（取自 /categories 的 code）；也可传空格分隔的字符串，如 "absolute false"。注意：不支持逗号分隔

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.text	string	被检测文本
data.length	integer	文本长度（字符）
data.passed	boolean	是否通过检测（无命中即为 true）
data.hit_count	integer	命中词数
data.risk_level	string	风险等级：high / medium / low
data.hits	array	命中记录列表
data.hits[]	object	单条命中记录
data.hits[].word	string	命中词
data.hits[].category	string	分类代码
data.hits[].category_name	string	分类名称
data.hits[].level	string	风险等级
data.hits[].positions	array	出现位置列表
data.hits[].positions[]	array	单个出现位置 [起始下标, 结束下标]
data.hits[].positions[][]	integer	位置下标（字符偏移）
data.hits[].law	string	法律依据
data.exempt_count	integer	被豁免的命中数
data.exempted_hits	array	被豁免的命中记录列表
data.exempted_hits[]	object	单条被豁免的命中记录（字段同 hits[]，另含 exempt_reason）
data.exempted_hits[].word	string	命中词
data.exempted_hits[].category	string	分类代码
data.exempted_hits[].category_name	string	分类名称
data.exempted_hits[].level	string	风险等级
data.exempted_hits[].positions	array	出现位置列表
data.exempted_hits[].positions[]	array	单个出现位置 [起始下标, 结束下标]
data.exempted_hits[].law	string	法律依据
data.exempted_hits[].exempt_reason	string	豁免原因

请求示例

返回示例

{"msg":"success","code":200,"data":{"hits":[{"law":"广告法第九条第三项","word":"国家级","level":"high","category":"absolute","positions":[[0,3]],"category_name":"绝对化用语"},{"law":"广告法第九条第三项","word":"最佳","level":"high","category":"absolute","positions":[[3,5]],"category_name":"绝对化用语"}],"text":"国家级最佳产品","length":7,"passed":false,"hit_count":2,"risk_level":"high","exempt_count":0,"exempted_hits":[]}}

批量检测

批量检测多段文本，单次最多 10 段，返回每段结果及聚合统计。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/ads/check-batch JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
texts	array	是	待检测文本数组（不能为空数组；最多 10 段，超出直接报错（4002）；单段超过 10240 字符时该条标记 error）
categories	array	否	限定检测分类代码数组（同 /check）；也可传空格分隔的字符串，不支持逗号分隔

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.total	integer	提交的总条数
data.returned	integer	本次实际返回条数
data.passed	integer	通过检测的条数
data.failed	integer	未通过检测的条数
data.max_level	string	全部结果中的最高风险等级
data.truncated	boolean	保留字段，当前恒为 false（超过 10 条时直接返回 4002 错误，不会截断）
data.max_limit	integer	单次允许检测的最大条数
data.list	array	检测结果列表，顺序与入参 texts 一致
data.list[]	object	单条检测结果
data.list[].text	string	被检测文本
data.list[].length	integer	文本长度（字符）
data.list[].passed	boolean	该条是否通过检测
data.list[].hit_count	integer	命中词数
data.list[].risk_level	string	风险等级：high / medium / low
data.list[].hits	array	命中记录列表
data.list[].hits[]	object	单条命中记录
data.list[].hits[].word	string	命中词
data.list[].hits[].category	string	分类代码
data.list[].hits[].category_name	string	分类名称
data.list[].hits[].level	string	风险等级
data.list[].hits[].positions	array	出现位置列表
data.list[].hits[].positions[]	array	单个出现位置 [起始下标, 结束下标]
data.list[].hits[].positions[][]	integer	位置下标（字符偏移）
data.list[].hits[].law	string	法律依据
data.list[].exempt_count	integer	该条被豁免的命中数
data.list[].exempted_hits	array	该条被豁免的命中记录列表
data.list[].exempted_hits[]	object	单条被豁免的命中记录（字段同 hits[]，另含 exempt_reason）
data.list[].exempted_hits[].word	string	命中词
data.list[].exempted_hits[].category	string	分类代码
data.list[].exempted_hits[].category_name	string	分类名称
data.list[].exempted_hits[].level	string	风险等级
data.list[].exempted_hits[].positions	array	出现位置列表
data.list[].exempted_hits[].law	string	法律依据
data.list[].exempted_hits[].exempt_reason	string	豁免原因
data.list[].error	string	该条处理失败时的错误标识，仅失败条目返回（目前仅 text_too_long）
data.list[].exempted_hits[].positions[]	array	单次出现位置 [start,end]
data.list[].exempted_hits[].positions[][]	integer	位置起止值（数组元素为 [start,end] 的两个整数）

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":[{"hits":[{"law":"广告法第九条第三项","word":"国家级","level":"high","category":"absolute","positions":[[0,3]],"category_name":"绝对化用语"},{"law":"广告法第九条第三项","word":"最佳","level":"high","category":"absolute","positions":[[3,5]],"category_name":"绝对化用语"}],"text":"国家级最佳产品","length":7,"passed":false,"hit_count":2,"risk_level":"high","exempt_count":0,"exempted_hits":[]},{"hits":[],"text":"本行业最佳实践","length":7,"passed":true,"hit_count":0,"risk_level":"low","exempt_count":1,"exempted_hits":[{"law":"广告法第九条第三项","word":"最佳","level":"high","category":"absolute","positions":[[3,5]],"category_name":"绝对化用语","exempt_reason":"前置豁免词: 行业"}]}],"total":2,"failed":1,"passed":1,"returned":2,"max_level":"high","max_limit":10,"truncated":false}}

产品说明

产品概述

基于《广告法》及相关法规对文本进行违禁词检测，返回命中词、风险等级与法律依据，支持单段与批量检测。

使用场景

数据查询：快速集成广告法违禁词检测到您的应用中

业务系统：将广告法违禁词检测数据嵌入业务流程

开发工具：通过 API 接口获取内容合规数据

数据分析：基于广告法违禁词检测数据进行分析和决策

费用计算

按次计费单价

¥0.002 / 次

每次调用接口从账户余额中扣除相应费用，VIP 用户可享折扣

扣费优先级

免费额度

次数包

余额扣费

计费方式详解

1 免费额度

· 接口每日免费额度已关闭
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。

2 次数包

预付费购买固定调用次数，最高可省 20%（相对按次付费），用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。

3 余额扣费

按次从账户余额扣除费用；所有用户可享量折扣，VIP 用户额外享 VIP 折扣。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣：个人版9折专业版8折企业版7折
量折扣：月付费调用 ≥1000 次享 2%、月付费调用 ≥10000 次享 5%、月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。

次数包方案

方案名称	调用次数	价格	折算单价	比按次付费节省	有效期
100次调用包	100 次	¥0.2	¥0.0020/次	-	365 天
500次调用包	500 次	¥0.95	¥0.0019/次	省5%	365 天
1000次调用包	1000 次	¥1.8	¥0.0018/次	省10%	365 天
5000次调用包	5000 次	¥8.5	¥0.0017/次	省15%	365 天
10000次调用包	10000 次	¥16	¥0.0016/次	省20%	365 天

VIP 权益对比

等级	每月免费次数	本接口月免费上限	折扣	VIP 折后单价
免费版	按接口配置	—	-	¥0.002/次
个人版	5000 次	5000 次	10%	¥0.0018/次
专业版	30000 次	30000 次	20%	¥0.0016/次
企业版推荐	200000 次	200000 次	30%	¥0.0014/次

* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度，本接口月免费上限为其中对本接口的限制（接口可单独设置上限或关闭）。VIP 折扣仅适用于余额扣费方式，VIP 折后单价不含量折扣。本接口已关闭接口级月度免费额度（不影响 VIP 月度免费额度）。接口每日免费额度已关闭。

费用计算示例

* 以下示例未包含量折扣，量折扣按账号当月全部接口的付费调用量另行计算。

示例1：普通用户按次付费

调用 1000 次，费用 = 0.002 × 1000 = ¥2.00

示例2：个人版用户按次付费（仅 VIP 折扣，已考虑最低利润率保护）

调用 1000 次，折扣约 10%，费用 = 0.002 × (1 - 10%) × 1000 ≈ ¥1.80

示例3：购买「500次调用包」次数包

支付 ¥0.95，获得 500 次调用，折算单价 ¥0.0019/次

同等次数按次付费需 ¥1.00，次数包可节省 ¥0.05

错误码说明

错误码	说明	解决方案
200	请求成功	-
400000	请求参数错误	检查参数名、格式与取值；具体原因见响应 msg
401000	认证失败	检查 Authorization: Bearer 密钥是否正确、是否过期
402000	账户余额不足	充值后重试
403000	无访问权限	确认密钥权限、接口范围与 IP 白名单是否满足要求
404001	接口或端点不存在	检查 API 与端点的请求路径
409000	请求冲突	请稍后重试
422000	参数校验失败	检查参数格式与取值
429000	请求频率或额度超限	降低调用频率，或升级套餐提升额度
500000	服务器内部错误	携带响应中的 request_id 联系技术支持
502000	服务暂时不可用	稍后重试
503000	服务暂时不可用	稍后重试
504000	请求超时	稍后重试

更新日志

暂无更新日志