DEVELOPERS

开发文档

从第一条请求，到适合业务的审核策略。

快速开始

注册账号，在控制台创建 API Key。未指定策略时，直接使用已发布的平台默认策略。请从服务端调用接口。

cURL

curl https://aimoderations.com/api/v2/moderation/check/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "今天的分享很有帮助，谢谢！"}'

Python

import os
import requests

response = requests.post(
    "https://aimoderations.com/api/v2/moderation/check/",
    headers={"Authorization": f"Bearer {os.environ['AIM_API_KEY']}"},
    json={"text": "今天的分享很有帮助，谢谢！"},
    timeout=120,
)
response.raise_for_status()
payload = response.json()
if payload["ok"]:
    print(payload["result"]["decision"])

请求参数

POST /api/v2/moderation/check/ · JSON · UTF-8

参数	类型	说明
`text`	string	必填，1–10,000 个字符。首尾空白会去除。
`policy_id`	UUID	可选，策略页面中的完整 ID。必须属于当前账号或为平台默认策略，且已发布、未停用。
`include_scores`	boolean	默认 false；true 时返回全部 219 个展示标签分数，合并项附带子规则明细。此参数不影响策略判断。
`label_view`	string	默认 display；设为 model 可按 236 个原始编码返回标签，名称使用新版名称，判断结果相同。

鉴权支持 Authorization: Bearer，也兼容 X-API-Key 请求头。

返回结果

以下为字段示例；策略 ID、版本和额度以实际响应为准。

{
  "ok": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "quota_remaining": 999,
  "result": {
    "decision": "PASS",
    "suggestion": "建议不拦截",
    "matched_labels": [],
    "matched_custom_rules": [],
    "custom_rule_match_count": 0,
    "custom_rule_matches_truncated": false,
    "policy": {
      "id": "7c8cdcd6-5b6e-4e42-a088-6533ad371234",
      "name": "标准审核策略",
      "version": 1
    },
    "text_length": 14,
    "quota_cost": 1
  }
}

字段	含义
`decision`	`PASS` 未触发当前策略；`BLOCK` 至少一个启用标签达到阈值，或命中词库 / 正则规则。
`matched_labels`	所有触发拦截的展示标签，包含 code、label、score、threshold、segment；合并项附带 members，明细中的 matched 标识实际触发的子规则。
`labels`	include_scores=true 时返回全部标签，另含 enabled、matched、polarity。
`policy`	实际使用的策略 ID、名称与发布版本。
`catalog_version`	策略使用的底层标签版本，保持兼容；展示名称和合并关系的版本见 display_catalog_version。

PASS 仅表示没有触发当前策略，不代表内容绝对安全。调用失败时不会返回 PASS。请使用 decision 和 code 做程序判断，展示文案不作为稳定接口。

策略与标签

策略选择顺序：请求指定 policy_id → Key 绑定策略 → 平台默认策略。指定无效策略时返回错误，不会静默切换。

提供 219 个展示标签，覆盖全部 236 条细分规则。17 组合并标签支持统一或分别设置开关和阈值；已有差异配置会保留。正向和中性标签初始不参与拦截。

模型先返回全部分数，再执行策略；任意片段触发规则都会建议拦截。正向标签不抵消其他命中。分数不是经过校准的违规概率。

保存草稿不会影响线上调用。发布后新请求采用新版本。平台默认策略更新只影响直接使用默认策略的请求，不会覆盖个人副本。

下载完整标签目录 JSON ↗

合并标签的分数与兼容性

合并项 code 沿用组内第一个原始编码，member_codes 列出全部原始编码。score 是子规则最高分；matched 为任一启用子规则达到自身阈值；enabled 表示至少一条子规则启用。配置一致时 rule_mode=shared，threshold 为共同阈值；配置不同时 rule_mode=individual，threshold=null，请读取 members 中各自的 threshold、enabled、score、matched 和 segment，不能只比较合并分数与阈值。

GET /api/v2/labels/ 返回 219 项展示目录，?view=model 返回全部 236 个原始编码及新版名称。V2 请求可设置 label_view=model 使用原始编码视图。

词库与正则

在控制台创建私有拦截词库或正则规则集，再到审核策略中勾选并发布。策略关联数量不设上限；每个账户最多维护 100 套启用的规则库。同一套规则可用于多个策略。管理员也可以为平台默认策略关联规则库。

词库使用字面包含匹配，每库最多 1,000 条，每条 100 字符；正则每库最多 50 条，每条 500 字符。默认忽略大小写，可单独关闭。正则使用 RE2 语法，不支持前后查找与反向引用；不要加 /…/ 分隔符。规则针对去除首尾空白后的全文，任一规则匹配（包括空串匹配）即建议拦截，正向标签不会抵消。

编辑或归档规则库不会改变现有策略快照。选择新版、保存草稿、测试并发布后才生效。恢复策略历史版本时也会恢复当时关联的词库和正则内容。

返回字段	含义
`matched_custom_rules`	命中依据，最多 50 条，每条规则仅记录首次匹配：type（keyword / regex）、library_id、library_name、library_revision、rule、match、start、end、match_truncated。位置是去除首尾空白后原文的字符索引，从 0 开始，end 不包含在内。命中片段最多返回 200 字符。未命中的词库内容不会出现在 API 响应中。
`custom_rule_match_count`	命中的自定义规则条数，不是词语出现次数。
`custom_rule_matches_truncated`	命中详情是否超过 50 条而被截断。

词库 / 正则检测失败或超出时间限制时返回 503，不扣额度，也不会返回 PASS。网页、V1 和 V2 均执行同一套策略；V1 的自定义规则命中还会在聚合字段中标记为 custom_rule，分数 1 表示确定性匹配。API 参数无需增加，继续通过 policy_id 或 Key 选择策略。

错误处理

HTTP	code	处理建议
400	invalid_request / invalid_text / invalid_policy	检查参数、策略归属与发布状态。
401 / 403	authentication_failed / not_authenticated	检查 Key 是否正确且启用。
403	quota_exhausted	额度不足，联系平台补充。
503	inference_error	检测未完成，可稍后重试。不要视为通过。

额度与限制

每 1024 个字符扣减 1 个额度，不足部分向上取整；失败不扣额度。单次最多 10,000 字符，长文本会分段审核，结果按标签取各段最高分。默认策略和自定义策略使用同一计费规则。

推理按短文本片段进行，跨片段语义可能影响结果；建议先用真实业务样本评估。接口没有幂等键，重复提交成功请求会重复计费。

V1 兼容说明

/api/v1/moderation/check/ 继续可用，保留已有聚合字段，labels 与 matched_labels 保持原始编码视图（全部分数为 236 项），使用新版标签名称。历史记录保留检测时的响应，不重写。新接入推荐使用 V2。