API reference

zhsafe checks Chinese text and returns one verdict, pass, review or block, with the categories that were flagged, the matched text and an English explanation.

The API takes and returns JSON over HTTPS. Send Content-Type: application/json with every request.

Examples on this page use https://zhsafe.tkl.ai.

Authentication

Every request carries an API key as a bearer token. Live keys start with zs_live_.

Authorization: Bearer zs_live_your_key

Keep keys on your server. Don't ship them in a mobile app or browser bundle; call zhsafe from your backend and pass the verdict on.

Check text

POST/v1/text/check

Checks one piece of text and returns a verdict.

Request

{
  "text": "加我微信 abc123 领优惠",
  "scene": "chat",
  "strategy": "fast",
  "cache": true,
  "explain": true,
  "metadata": { "user_id": "u_123" }
}

Scenes

Strategies

Response

{
  "id": "chk_01J8Z3K6T2QF9W4M7XN5B0D1RE",
  "verdict": "block",
  "categories": [
    {
      "category": "ads",
      "score": 0.92,
      "agreement": 1,
      "spans": [{ "start": 0, "end": 11, "text": "加我微信 abc123" }],
      "explanation": "Asks users to add an outside WeChat account to claim a discount, which moves them off your platform."
    }
  ],
  "strategy": "consensus",
  "cached": false,
  "latency_ms": 312
}

Batch check

POST/v1/text/check/batch

Checks up to 100 texts in one request. Each item takes its own scene and metadata; strategy, cache and explain apply to the whole batch. Each item counts as one check.

{
  "strategy": "fast",
  "items": [
    { "text": "快乐小熊猫", "scene": "nickname", "metadata": { "user_id": "u_123" } },
    { "text": "全网最低价！第一品牌纯棉T恤", "scene": "ad" }
  ]
}

The response holds one result per item, in the same order as items. Each result has the same shape as a single check. If one item fails, its position holds an error object instead, and the other items are unaffected.

{
  "results": [
    { "id": "chk_...", "verdict": "pass", "categories": [], "strategy": "fast", "cached": true, "latency_ms": 4 },
    { "id": "chk_...", "verdict": "block", "categories": [{ "category": "ads", "score": 0.88, "agreement": 1, "spans": [{ "text": "最低价" }, { "text": "第一" }] }], "strategy": "fast", "cached": false, "latency_ms": 287 },
    { "error": { "code": "invalid_request", "message": "`text` must be a non-empty string" } }
  ]
}

Feedback

POST/v1/feedback

Tells us a verdict was wrong. Corrections go into a review queue. Once a correction is confirmed, cached results for the same text are refreshed, so it gets the corrected verdict next time.

{
  "id": "chk_01J8Z3K6T2QF9W4M7XN5B0D1RE",
  "expected": "pass",
  "note": "Game term, not an ad."
}

A queued correction returns 200 with { "ok": true }. You can only correct checks made with your own key; any other id returns 404 not_found.

Verdicts

Policies usually differ per category. A game might let mild abuse through with a warning while always blocking politics. Read categories rather than only verdict when you need that control.

Categories

Every engine's labels are mapped onto this one set. Categories are kept separate rather than merged, so you can set a policy for each.

Errors

Errors use standard HTTP status codes and a JSON body with a stable code and a readable message.

{
  "error": {
    "code": "invalid_request",
    "message": "text is required"
  }
}

Code examples

Check a chat message and act on the verdict. Set ZHSAFE_KEY to your API key.

curl https://zhsafe.tkl.ai/v1/text/check \
  -H "Authorization: Bearer $ZHSAFE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "加我微信 abc123 领优惠", "scene": "chat", "explain": true}'

# Batch
curl https://zhsafe.tkl.ai/v1/text/check/batch \
  -H "Authorization: Bearer $ZHSAFE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"text": "快乐小熊猫", "scene": "nickname"}, {"text": "周末一起组队吗？", "scene": "chat"}]}'

// Node 18+ or any runtime with fetch. Run this on your server, not in the browser.
async function checkText(text, scene = "chat") {
  const res = await fetch("https://zhsafe.tkl.ai/v1/text/check", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.ZHSAFE_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text, scene, explain: true }),
  });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`zhsafe ${res.status} ${error.code}: ${error.message}`);
  }
  return res.json();
}

const result = await checkText("加我微信 abc123 领优惠");
if (result.verdict === "block") {
  // reject the message
} else if (result.verdict === "review") {
  // hold for a moderator
}
for (const c of result.categories) {
  console.log(c.category, c.score, c.explanation);
}

import os
import requests

def check_text(text, scene="chat"):
    resp = requests.post(
        "https://zhsafe.tkl.ai/v1/text/check",
        headers={"Authorization": f"Bearer {os.environ['ZHSAFE_KEY']}"},
        json={"text": text, "scene": scene, "explain": True},
        timeout=10,
    )
    if not resp.ok:
        err = resp.json()["error"]
        raise RuntimeError(f"zhsafe {resp.status_code} {err['code']}: {err['message']}")
    return resp.json()

result = check_text("加我微信 abc123 领优惠")
if result["verdict"] == "block":
    pass  # reject the message
elif result["verdict"] == "review":
    pass  # hold for a moderator
for c in result["categories"]:
    print(c["category"], c["score"], c.get("explanation"))