Developer documentation

Quick start

Create an account and an API key in the console. Requests without a custom policy use the published platform default. Call the API from your server.

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"])

Request parameters

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

Use Authorization: Bearer. X-API-Key is also supported.

Response

Illustrative response. IDs, versions and credits depend on the actual request.

{
  "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
  }
}

PASS means no rule triggered in this policy, not absolute safety. Failures never return PASS. Branch on decision and code; display text is not a stable API contract.

Policies & labels

Selection order: explicit policy_id → key binding → platform default. An invalid policy returns an error without falling back.

219 display labels cover all 236 underlying rules. The 17 merged groups support shared or individual settings; existing differences are preserved. Positive and neutral labels are disabled by default.

Policies use all scores. A triggered rule in any segment produces BLOCK. Positive labels do not cancel other hits. Scores are not calibrated violation probabilities.

Draft saves do not affect live traffic. New requests use a version after publication. Default-policy updates do not overwrite personal copies.

View the full label catalogue JSON ↗

Merged scores and compatibility

A merged code reuses the first original code; member_codes lists all original codes. score is the maximum member score, matched is true when any enabled member meets its own threshold, and enabled means any member is enabled. Identical settings use rule_mode=shared and a common threshold. Differing settings use rule_mode=individual and threshold=null; inspect members for each threshold, enabled, score, matched and segment. Do not infer a decision from the merged score alone.

GET /api/v2/labels/ returns 219 display labels; ?view=model returns all 236 original codes with updated names. V2 requests can use label_view=model for the original-code view.

Custom rule libraries

Create private keyword or regex libraries in the console, then select and publish them in a policy. There is no per-policy attachment limit; each account supports 100 active libraries. Libraries are reusable across policies, including the platform default managed by administrators.

Keywords use literal substring matching: 1,000 entries per library, 100 characters each. Regex libraries allow 50 patterns of 500 characters each. Case-insensitive matching is enabled by default and can be disabled. RE2 syntax is supported without lookaround or backreferences; omit /…/ delimiters. Rules search the complete trimmed input. Any match, including an empty match, recommends blocking; positive labels do not override it.

Editing or archiving a library does not change existing policy snapshots. Select an updated version, save, test and publish to apply it. Restoring a policy version also restores its library contents.

Custom-rule failures or time-budget exhaustion return 503 without charging credits or returning PASS. Web, V1 and V2 apply the same policy. V1 aggregates additionally use custom_rule with score 1 for a deterministic match. No new request parameters are needed: select a policy using policy_id or the key binding.

Error handling

Usage & limits

One credit per 1,024 characters, rounded up. Failed checks are not charged. Maximum 10,000 characters. Long text is segmented; each label uses its highest score across segments. All policies share the same billing rules.

Short segments may lose cross-segment context; evaluate on representative samples. There is no idempotency key, so repeated successful submissions consume credits again.

V1 compatibility

/api/v1/moderation/check/ remains available with legacy aggregates. labels and matched_labels retain original codes (236 full scores) with updated names. Historical responses are preserved as recorded. New integrations should use V2.