稽核配置與詞庫

從你的服務端維護詞庫、修改稽核配置、檢查文字，與控制檯“內容安全”中的“配置”“詞庫”和“試一試”相同。配置和詞庫的含義見內容安全，在控制檯中的操作見內容安全配置。

例如，建一個拒絕導流的詞庫，加兩個詞，再試一段文字：

bash

LIST=$(curl -s -X POST "$IM_API/$ORG/$APP/moderation/word-lists" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "导流", "action": "reject", "category": "ad" }' | jq -r .list_id)

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists/$LIST/words/batch" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "words": ["加微信", "加QQ"] }'

curl -X POST "$IM_API/$ORG/$APP/moderation/text-check" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "scene": "message", "text": "有需要请加 微 信" }'
# 词库修改通常 1 秒内生效；结果的 action 为 reject

要做什麼	介面
建、改、刪詞庫	建立詞庫、修改詞庫、刪除詞庫
加詞、刪詞、查詞	新增詞條、刪除詞條、查詢詞條
驗證一段文字會不會被攔	檢查文字
開關第三方稽核、設定自動處罰、讓服務端提交的內容也檢查	修改稽核配置

生效時間：修改配置、詞庫和詞條後，通常在 1 秒內生效，最遲 30 秒。可以用檢查文字立即驗證。
稽核賬號：第三方稽核賬號只能在控制檯中新增和選擇，這些介面不能修改 provider_account_id。為場景開啟第三方稽核之前，要先在控制檯為應用選擇賬號。
平臺的設定：配置中的 platform 是平臺對本應用的設定，只能檢視。
操作日誌：修改配置、詞庫和詞條的請求寫入操作日誌，操作人為呼叫所用的服務端金鑰。
呼叫額度：新增和刪除詞條按詞條數計入應用的 OpenAPI 呼叫額度，見批次介面。

查詢稽核配置

查詢應用當前的稽核配置。scenes 中返回全部場景的設定，沒有修改過的為預設值。

GET/{org_name}/{app_name}/moderation/config

路徑引數

org_name、app_name 見接入概述。

請求示例

bash

curl "$IM_API/$ORG/$APP/moderation/config" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為稽核配置物件。

json

{
  "scenes": {
    "chatroom_attribute": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "chatroom_message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "chatroom_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "friend_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_member": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "media_upload": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "user_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    }
  },
  "custom_message_check": "strings",
  "provider_account_id": null,
  "sync_timeout_ms": 800,
  "on_timeout": "pass",
  "penalty_rules": [
    {
      "window_hours": 24,
      "threshold": 3,
      "categories": null,
      "action": "mute",
      "mute_scopes": [
        "chat",
        "group"
      ],
      "duration_seconds": 3600
    },
    {
      "window_hours": 168,
      "threshold": 10,
      "categories": null,
      "action": "disable",
      "mute_scopes": null,
      "duration_seconds": 604800
    }
  ],
  "platform": {
    "rules_enabled": true,
    "scenes": {},
    "daily_quota": 100000,
    "enforced_categories": [
      "politics",
      "terrorism",
      "porn"
    ],
    "inherited_scenes": true,
    "inherited_daily_quota": true
  },
  "version": 8,
  "updated_at": "2026-10-04T19:37:43.590Z"
}

修改稽核配置

只傳要修改的項，沒有傳的項保持不變：

scenes 按場景合併：只修改請求中給出的場景和欄位；
category_actions 按類別合併：某個類別傳 null 表示恢復預設的處理；
penalty_rules 整體替換：傳新的全部規則，傳 null 表示不自動處罰。

修改後沒有任何變化的，version 不變。

PATCH/{org_name}/{app_name}/moderation/config

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
`scenes`	Object	否	要修改的場景，鍵為場景，值為場景設定中要修改的欄位
`custom_message_check`	String	否	自定義訊息的檢查方式：`strings` 檢查 `body` 中的全部字串值，`off` 不檢查
`category_actions`	Object	否	要修改的類別的處理，鍵為類別，值為類別的處理中要修改的欄位，或 `null`（恢復預設）
`sync_timeout_ms`	Number	已停用，不再起作用，預設 800
`on_timeout`	String	已停用，不再起作用，預設 `pass`
`penalty_rules`	Array<Object>	否	自動處罰規則，最多 5 條，整體替換，見自動處罰規則；`null` 或空陣列表示不自動處罰
`version`	Number	否	讀取到的 `version`。給出時與當前版本不一致返回 `409 version_conflict`，見併發修改

請求體中不能出現 provider_account_id（即使值為 null），否則返回 400 invalid_argument。platform 可以出現，但會被忽略，所以可以把查詢到的配置改完後整體提交（去掉 provider_account_id）。

請求示例

讓服務端提交的群資料也按你的規則檢查，第三方稽核建議攔截的廣告改為送審，等待時限改為 1 秒：

bash

curl -X PATCH "$IM_API/$ORG/$APP/moderation/config" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenes": { "group_profile": { "include_server_sent": true } },
    "category_actions": { "ad": { "block": "review" } },
    "sync_timeout_ms": 1000,
    "version": 8
  }'

響應

成功返回 200 OK，響應體為修改後的稽核配置物件。

json

{
  "scenes": {
    "chatroom_attribute": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "chatroom_message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "chatroom_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "friend_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_member": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "group_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "media_upload": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "user_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    }
  },
  "custom_message_check": "strings",
  "provider_account_id": null,
  "category_actions": {
    "ad": {
      "block": "review",
      "review": "review"
    }
  },
  "sync_timeout_ms": 1000,
  "on_timeout": "pass",
  "penalty_rules": [
    {
      "window_hours": 24,
      "threshold": 3,
      "categories": null,
      "action": "mute",
      "mute_scopes": [
        "chat",
        "group"
      ],
      "duration_seconds": 3600
    },
    {
      "window_hours": 168,
      "threshold": 10,
      "categories": null,
      "action": "disable",
      "mute_scopes": null,
      "duration_seconds": 604800
    }
  ],
  "platform": {
    "rules_enabled": true,
    "scenes": {},
    "daily_quota": 100000,
    "enforced_categories": [
      "politics",
      "terrorism",
      "porn"
    ],
    "inherited_scenes": true,
    "inherited_daily_quota": true
  },
  "version": 9,
  "updated_at": "2026-10-04T19:49:55.426Z"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	取值不合法，`details.field` 指出欄位，如 `scenes`（場景不存在）、`sync_timeout_ms`、`on_timeout`、`custom_message_check`、`category_actions`、`penalty_rules`；請求體中有 `provider_account_id` 時 `details.field` 為 `provider_account_id`
400	`invalid_argument`	`details.reason` 為 `unsupported_scene`：場景不支援這種稽核方式，如 `media_provider` 為 `async` 用於沒有媒體的場景，見場景設定
400	`invalid_argument`	`details.reason` 為 `provider_account_required`：開啟了第三方稽核，但應用還沒有在控制檯選擇稽核賬號
409	`limit_exceeded`	`details.reason` 為 `penalty_rule_limit`：自動處罰規則超過 5 條
409	`version_conflict`	`version` 與當前版本不一致，`details.current` 為當前的 `version` 和 `updated_at`

json

{
  "error": {
    "code": "version_conflict",
    "message": "数据已被其他人修改，请刷新后重试",
    "details": {
      "current": {
        "updated_at": "2026-10-04T19:49:55.426Z",
        "version": 9
      }
    },
    "request_id": "7FPY7Z2Q5BVEIVC7MDNLTVJFJN"
  }
}

詞庫

每個應用最多 20 個詞庫，每個詞庫最多 10000 個詞條，應用合計最多 50000 個詞條。詞庫的屬性和匹配規則見詞庫。

查詢詞庫列表

查詢應用的全部詞庫，不分頁，按建立時間排列。

GET/{org_name}/{app_name}/moderation/word-lists

路徑引數

org_name、app_name 見接入概述。

請求示例

bash

curl "$IM_API/$ORG/$APP/moderation/word-lists" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 為詞庫物件的陣列。

json

{
  "items": [
    {
      "list_id": "100311111194116096",
      "name": "广告导流",
      "kind": "block",
      "action": "reject",
      "match_mode": "contains",
      "category": "ad",
      "scenes": null,
      "enabled": true,
      "word_count": 4,
      "created_at": "2026-10-04T19:20:32.603Z",
      "updated_at": "2026-10-04T19:20:41.046Z"
    },
    {
      "list_id": "100311111538049024",
      "name": "不文明用语",
      "kind": "block",
      "action": "replace",
      "match_mode": "contains",
      "category": "abuse",
      "scenes": null,
      "enabled": true,
      "word_count": 2,
      "created_at": "2026-10-04T19:20:32.683Z",
      "updated_at": "2026-10-04T19:30:08.569Z"
    }
  ]
}

建立詞庫

POST/{org_name}/{app_name}/moderation/word-lists

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
`name`	String	是	名稱，1 到 64 個字元，不能包含控制字元，在應用內不能重複
`kind`	String	否	種類：`block` 遮蔽（預設）、`allow` 放行。建立後不能修改
`action`	String	視種類而定	遮蔽詞庫必填：`reject` 拒絕、`replace` 替換、`review` 送審。放行詞庫不能填寫
`match_mode`	String	否	匹配方式：`contains` 包含（預設）、`exact` 完全相同。放行詞庫只能為 `contains`
`category`	String	否	命中時記入的類別，預設為 `custom`
`scenes`	Array<String>	否	適用的場景，不能為空陣列；省略或為 `null` 時適用於全部場景
`enabled`	Boolean	否	是否啟用，預設為 `true`

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "联系方式导流",
    "kind": "block",
    "action": "review",
    "match_mode": "contains",
    "category": "ad",
    "scenes": ["message", "chatroom_message"],
    "enabled": true
  }'

響應

成功返回 201 Created，響應體為詞庫物件。

json

{
  "list_id": "100318615084990464",
  "name": "联系方式导流",
  "kind": "block",
  "action": "review",
  "match_mode": "contains",
  "category": "ad",
  "scenes": [
    "message",
    "chatroom_message"
  ],
  "enabled": true,
  "word_count": 0,
  "created_at": "2026-10-04T19:50:21.669Z",
  "updated_at": "2026-10-04T19:50:21.669Z"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	取值不合法，`details.field` 指出欄位；名稱已被本應用的其他詞庫使用時 `details.field` 為 `name`；`scenes` 為空陣列時為 `scenes`
400	`invalid_argument`	`details.reason` 為 `unsupported_action`：遮蔽詞庫沒有給出 `action`，或放行詞庫給出了 `action`
409	`limit_exceeded`	`details.reason` 為 `word_list_limit`：應用的詞庫已有 20 個

查詢詞庫

GET/{org_name}/{app_name}/moderation/word-lists/{list_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`list_id`	String	詞庫 ID

請求示例

bash

curl "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為詞庫物件。

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	詞庫不存在，或不屬於這個應用

修改詞庫

修改詞庫的屬性，只傳要修改的欄位。種類 kind 不能修改。

PATCH/{org_name}/{app_name}/moderation/word-lists/{list_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`list_id`	String	詞庫 ID

請求體

欄位同建立詞庫，都是可選的，不能包含 kind。scenes 傳 null 表示改為適用於全部場景。

請求示例

bash

curl -X PATCH "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "联系方式导流（消息）",
    "action": "reject",
    "scenes": null
  }'

響應

成功返回 200 OK，響應體為修改後的詞庫物件。

json

{
  "list_id": "100318615084990464",
  "name": "联系方式导流（消息）",
  "kind": "block",
  "action": "reject",
  "match_mode": "contains",
  "category": "ad",
  "scenes": null,
  "enabled": true,
  "word_count": 0,
  "created_at": "2026-10-04T19:50:21.669Z",
  "updated_at": "2026-10-04T19:50:28.250Z"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	取值不合法，`details.field` 指出欄位；請求中有 `kind` 時 `details.field` 為 `kind`
400	`invalid_argument`	`details.reason` 為 `unsupported_action`：修改後的遮蔽詞庫沒有處理方式，或給放行詞庫設定了 `action`
404	`not_found`	詞庫不存在

刪除詞庫

刪除詞庫和其中的全部詞條，不能恢復。

DELETE/{org_name}/{app_name}/moderation/word-lists/{list_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`list_id`	String	詞庫 ID

請求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/moderation/word-lists/100318861361938432" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 204 No Content，沒有響應體。

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	詞庫不存在，或已被刪除

查詢詞條

按規範化之後的詞條排序，分頁查詢詞庫中的詞條，見分頁。

GET/{org_name}/{app_name}/moderation/word-lists/{list_id}/words

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`list_id`	String	詞庫 ID

查詢引數

引數	型別	必填	說明
`prefix`	String	否	只返回以它開頭的詞條。按規範化之後的結果匹配，如 `加 Q` 與 `加q` 相同
`limit`	Number	否	每頁的條數，預設 20，最大 500
`cursor`	String	否	上一頁返回的 `next_cursor`

請求示例

bash

curl "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464/words?limit=2" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`items`	Array<Object>	詞條物件的陣列
`next_cursor`	String	下一頁的遊標，沒有下一頁時為 `null`

json

{
  "items": [
    {
      "word": "qq号",
      "original": "ｑｑ号",
      "created_at": "2026-10-04T19:50:33.933Z"
    },
    {
      "word": "二维码进群",
      "original": "二维码进群",
      "created_at": "2026-10-04T19:50:33.933Z"
    }
  ],
  "next_cursor": "二维码进群"
}

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	詞庫不存在

新增詞條

向詞庫中新增詞條，一次 1 到 1000 個。每個詞條先規範化，規範化後與已有詞條（或同一次提交中的其他詞條）相同的視為重複，不合法的不新增，其餘正常新增。

POST/{org_name}/{app_name}/moderation/word-lists/{list_id}/words/batch

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`list_id`	String	詞庫 ID

請求體

欄位	型別	必填	說明
`words`	Array<String>	是	要新增的詞條，1 到 1000 個。遮蔽詞規範化後為 2 到 32 個字元，放行詞為 2 到 64 個字元；原樣最多 64 個字元，不能包含控制字元

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464/words/batch" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "words": ["加QQ", "加 Q Q", "ｑｑ号", "扣扣", "x", "二维码进群"]
  }'

響應

成功返回 200 OK：

欄位	型別	說明
`added`	Number	新增的詞條數
`duplicated`	Array<String>	重複的詞條（原樣）
`invalid`	Array<Object>	不合法的詞條，每項為原樣 `word` 和原因 `reason`：`too_short` 太短、`too_long` 太長、`control_character` 含控制字元

例子中“加 Q Q”規範化後為 加qq，與同時提交的“加QQ”重複；“ｑｑ號”規範化後為 qq号：

json

{
  "added": 4,
  "duplicated": [
    "加 Q Q"
  ],
  "invalid": [
    {
      "reason": "too_short",
      "word": "x"
    }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.field` 為 `words`：`words` 為空或超過 1000 個
404	`not_found`	詞庫不存在
409	`limit_exceeded`	`details.reason` 為 `word_limit`：新增後詞庫超過 10000 個詞條，或應用合計超過 50000 個。這時整批都不新增

刪除詞條

從詞庫中刪除詞條，一次 1 到 1000 個。詞條可以是原樣，也可以是規範化之後的結果，按規範化之後的結果刪除；不存在的詞條忽略。

POST/{org_name}/{app_name}/moderation/word-lists/{list_id}/words/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`list_id`	String	詞庫 ID

請求體

欄位	型別	必填	說明
`words`	Array<String>	是	要刪除的詞條，1 到 1000 個

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464/words/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "words": ["扣扣", "加 qq", "不存在的词"]
  }'

響應

成功返回 200 OK，removed 為刪除的詞條數：

json

{
  "removed": 2
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.field` 為 `words`：`words` 為空或超過 1000 個
404	`not_found`	詞庫不存在

檢查文字

按應用當前的全部規則檢查一段文字或多個欄位，返回結果和命中的詞，用於修改詞庫後驗證，或在你自己的業務中預先檢查使用者輸入。檢查按客戶端提交的內容處理（平臺規則和你的規則都適用），不生成稽核記錄和違規，不計入統計。

平臺詞庫的命中只返回 platform 和類別，不返回詞庫和命中的詞。

POST/{org_name}/{app_name}/moderation/text-check

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
`scene`	String	是	場景，按這個場景適用的詞庫和設定檢查，取值見稽核的內容和時機
`text`	String	二選一	要檢查的一段文字
`fields`	Object	二選一	要檢查的多個欄位，鍵為欄位名，值為文字，與 `text` 合計最多 10 個
`with_provider`	Boolean	否	是否同時用智慧稽核檢查，預設為 `true`：關鍵詞和智慧稽核一起檢查，這個場景開啟了文字稽核時同步呼叫智慧稽核，計入用量和費用；智慧稽核沒有執行時只用關鍵詞的結果，原因見 `provider_skipped`。為 `false` 時只查關鍵詞

請求示例

檢查一段文字：

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/text-check" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scene": "message",
    "text": "想要资料请扫二维码进群，你个笨蛋"
  }'

檢查多個欄位：

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/text-check" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scene": "group_profile",
    "fields": { "name": "周末兼职刷单群", "announcement": "欢迎新人" }
  }'

響應

成功返回 200 OK。只給出 text 時，響應體為一個檢查結果物件：

json

{
  "action": "reject",
  "hits": [
    {
      "list_id": "100318615084990464",
      "list_name": "联系方式导流（消息）",
      "category": "ad",
      "action": "reject",
      "word": "二维码进群",
      "start": 6,
      "end": 11
    },
    {
      "list_id": "100311111538049024",
      "list_name": "不文明用语",
      "category": "abuse",
      "action": "replace",
      "word": "笨蛋",
      "start": 14,
      "end": 16
    }
  ],
  "provider_result": null,
  "text": "想要资料请扫二维码进群，你个**"
}

給出 fields 時，響應體為 { "fields": { 字段名: 检查结果对象 } }；同時給出了 text 的，結果中另有一個名為 text 的欄位：

json

{
  "fields": {
    "announcement": {
      "action": "reject",
      "hits": [],
      "provider_result": {
        "categories": [
          "gambling"
        ],
        "suggestion": "block"
      },
      "text": "欢迎新人"
    },
    "name": {
      "action": "review",
      "hits": [
        {
          "list_id": "100311111852621824",
          "list_name": "疑似诈骗",
          "category": "fraud",
          "action": "review",
          "word": "兼职刷单",
          "start": 2,
          "end": 6
        }
      ],
      "provider_result": {
        "categories": [
          "vulgar"
        ],
        "suggestion": "review"
      },
      "text": "周末兼职刷单群"
    }
  }
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.field` 為 `scene`：場景不合法；為 `fields`：`text` 和 `fields` 都沒有給出，或合計超過 10 個

資料結構

稽核配置物件

欄位	型別	說明
`scenes`	Object	全部場景的設定，鍵為場景，值為場景設定
`custom_message_check`	String	自定義訊息的檢查方式：`strings` 檢查 `body` 中的全部字串值（預設），`off` 不檢查
`provider_account_id`	String	應用在控制檯選擇的稽核賬號 ID，沒有選擇時為 `null`
`category_actions`	Object	修改過的類別的處理，鍵為類別，值為類別的處理。沒有修改過的類別取預設值；都沒有修改過時不返回這個欄位
`sync_timeout_ms`	Number	已停用，不再起作用，預設 800
`on_timeout`	String	已停用，不再起作用，預設 `pass`
`penalty_rules`	Array<Object>	自動處罰規則，沒有規則時為 `null` 或空陣列
`platform`	Object	平臺對本應用的設定，只讀，見下表
`version`	Number	配置的版本號，每次修改加一。沒有修改過的應用為 `1`
`updated_at`	String	最近一次修改的時間，沒有修改過為 `null`

platform 的欄位：

欄位	型別	說明
`rules_enabled`	Boolean	平臺規則是否對本應用生效
`scenes`	Object	平臺用平臺的賬號為本應用做第三方稽核的場景，鍵為場景，值為 `text_provider` 和 `media_provider`；沒有時為空物件
`daily_quota`	Number	平臺賬號每天為本應用稽核的次數上限，`0` 表示不限
`enforced_categories`	Array<String>	平臺強制處理的類別
`inherited_scenes`	Boolean	`scenes` 是否為平臺的預設設定（平臺沒有為本應用單獨設定）
`inherited_daily_quota`	Boolean	`daily_quota` 是否為平臺的預設設定

場景設定

欄位	型別	說明
`enabled`	Boolean	是否按你的規則檢查這個場景，預設為 `true`。為 `false` 時只按平臺規則檢查
`text_provider`	String	文字的第三方稽核：`off` 不稽核（預設）、`async` 在傳送、儲存之後稽核。舊的取值 `sync` 按 `async` 處理
`media_provider`	String	圖片、語音、影片的第三方稽核：`off`（預設）、`async`（傳送、儲存之後稽核）
`include_server_sent`	Boolean	你的服務端和控制檯提交的內容是否也按你的規則檢查，預設為 `false`

第三方稽核一律在內容發出、儲存之後進行，傳送和儲存時只檢查詞庫，不等待服務商。違規的訊息自動撤回，違規的資料和頭像自動清除；需要「發不出去」的內容請加入詞庫。

各場景可以使用的取值：

場景	`text_provider`	`media_provider`	`include_server_sent`
`message`、`chatroom_message`	`off`、`async`	`off`、`async`	可以設定
`user_profile`、`group_profile`	`off`、`async`	`off`、`async`（頭像）	可以設定
`group_member`、`group_request`、`friend_request`、`chatroom_profile`	`off`、`async`	`off`	可以設定
`media_upload`	`off`	`off`、`async`	可以設定
`chatroom_attribute`	`off`	`off`	只能為 `false`

任何場景的 text_provider 或 media_provider 不為 off 時，應用必須已在控制檯選擇稽核賬號。

類別的處理

第三方稽核結果的處理，平臺強制處理的類別不受影響。

欄位	型別	說明
`block`	String	建議攔截時：`reject` 拒絕（預設）、`review` 送審
`review`	String	建議人工稽核時：`review` 送審（預設）、`none` 不處理

自動處罰規則

欄位	型別	說明
`window_hours`	Number	時間視窗，1 到 720 小時
`threshold`	Number	時間視窗內的違規次數，1 到 1000
`categories`	Array<String>	只統計這些類別的違規；`null` 統計全部類別
`action`	String	處罰：`mute` 全域性禁言、`disable` 封禁
`mute_scopes`	Array<String>	禁言的場景，`action` 為 `mute` 時必填：`chat`、`group`、`room` 中的一個或多個；`action` 為 `disable` 時為 `null`
`duration_seconds`	Number	處罰的時長，1 到 315360000 秒（10 年）；`null` 為永久

規則的執行方式見違規記錄與自動處罰。

詞庫物件

欄位	型別	說明
`list_id`	String	詞庫 ID
`name`	String	名稱
`kind`	String	種類：`block` 遮蔽、`allow` 放行
`action`	String	處理方式：`reject`、`replace`、`review`；放行詞庫為 `null`
`match_mode`	String	匹配方式：`contains` 包含、`exact` 完全相同
`category`	String	命中時記入的類別
`scenes`	Array<String>	適用的場景；`null` 表示全部場景
`enabled`	Boolean	是否啟用
`word_count`	Number	詞條數
`created_at`	String	建立時間
`updated_at`	String	最近一次修改詞庫或詞條的時間

json

{
  "list_id": "100318615084990464",
  "name": "联系方式导流",
  "kind": "block",
  "action": "review",
  "match_mode": "contains",
  "category": "ad",
  "scenes": [
    "message",
    "chatroom_message"
  ],
  "enabled": true,
  "word_count": 0,
  "created_at": "2026-10-04T19:50:21.669Z",
  "updated_at": "2026-10-04T19:50:21.669Z"
}

詞條物件

欄位	型別	說明
`word`	String	規範化之後的詞條，匹配時使用它
`original`	String	新增時提交的原樣
`created_at`	String	新增的時間

檢查結果物件

欄位	型別	說明
`action`	String	結果：`pass` 透過、`reject` 拒絕、`replace` 替換、`review` 送審
`text`	String	替換之後的文字；沒有命中替換的詞時與原文相同
`hits`	Array<Object>	命中的詞庫，見下表；沒有命中時為空陣列
`provider_result`	Object	智慧稽核的結果：`suggestion` 為建議（`pass` 透過、`review` 建議人工稽核、`block` 建議攔截），`categories` 為類別。沒有呼叫或呼叫失敗時為 `null`
`provider_skipped`	String	智慧稽核這次沒有執行的原因，執行了或傳了 `with_provider: false` 時為 `null`：`not_enabled` 這個場景沒有開啟文字稽核、`no_account` 平臺暫未提供文字稽核、`not_entitled` 套餐不含平臺內容稽核、`quota` 當天的稽核額度已用完且稽核餘額不足、`failed` 智慧稽核暫時不可用。沒有執行時結果只來自關鍵詞

hits 的每一項：

欄位	型別	說明
`list_id`	String	詞庫 ID。平臺詞庫的命中沒有這個欄位
`list_name`	String	詞庫的名稱。平臺詞庫的命中沒有這個欄位
`platform`	Boolean	平臺詞庫的命中為 `true`，只帶 `category`；你的詞庫的命中沒有這個欄位
`category`	String	詞庫的類別
`action`	String	詞庫的處理方式
`word`	String	命中的詞條（規範化之後的）
`start`、`end`	Number	命中在原文中的位置，按字元計算，從 0 開始，`end` 不包含

稽核配置與詞庫 ​

查詢稽核配置 ​

路徑引數 ​

請求示例 ​

響應 ​

修改稽核配置 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

詞庫 ​

查詢詞庫列表 ​

路徑引數 ​

請求示例 ​

響應 ​

建立詞庫 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢詞庫 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

修改詞庫 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

刪除詞庫 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢詞條 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

新增詞條 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

刪除詞條 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

檢查文字 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

稽核配置物件 ​

場景設定 ​

類別的處理 ​

自動處罰規則 ​

詞庫物件 ​

詞條物件 ​

檢查結果物件 ​

稽核配置與詞庫

查詢稽核配置

路徑引數

請求示例

響應

修改稽核配置

路徑引數

請求體

請求示例

響應

錯誤

詞庫

查詢詞庫列表

路徑引數

請求示例

響應

建立詞庫

路徑引數

請求體

請求示例

響應

錯誤

查詢詞庫

路徑引數

請求示例

響應

錯誤

修改詞庫

路徑引數

請求體

請求示例

響應

錯誤

刪除詞庫

路徑引數

請求示例

響應

錯誤

查詢詞條

路徑引數

查詢引數

請求示例

響應

錯誤

新增詞條

路徑引數

請求體

請求示例

響應

錯誤

刪除詞條

路徑引數

請求體

請求示例

響應

錯誤

檢查文字

路徑引數

請求體

請求示例

響應

錯誤

資料結構

稽核配置物件

場景設定

類別的處理

自動處罰規則

詞庫物件

詞條物件

檢查結果物件