> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/chinese-simplified/api-wen-dang-yong-hu-ming.md). # API 文档：用户名 ## **简介** GGWP 提供了一个 API，您可以用来处理用户名数据，并将操作集成到您的应用工作流中。该产品旨在识别与用户名相关的各种有害内容类型，包括类似的使用场景，如队伍名和公会名，无论是在创建时，还是在用户进行更改或新的社交趋势出现并改变“何为有害内容”的定义之后的长期使用过程中。 ## 入门指南 在开始使用 API 之前，了解该产品的工作方式非常重要，这样才能充分发挥其潜力。 ### **了解 GGWP 的用户名审核解决方案** 该产品的主要用途是防止产生对其他社区成员可能造成冒犯的有害用户名和队伍名。此外，该工具还可用于发现可能会随着时间推移变得有害的现有用户名，以及验证和分流用户针对他人用户名提交的举报。 您将对每个单独的用户名调用 1 次 API，并包含一个用于跟踪发送方的唯一标识符（更多信息请参见下方“用户名 API”部分）。GGWP 会负责处理这些信息，并提供与该用户名及其背后用户相关的洞察。 当响应返回给您后，我们建议集成不同的操作，以提升平台上的用户体验。一些示例操作包括提示新用户选择其他用户名，或通知现有用户需要修改其个人资料名称。 ### **可配置设置** 可以定义自定义设置，以选择您希望在平台用户名中阻止的内容类型。这可以通过 2 种方式完成： * 在入驻时（推荐）——您将所需配置分享给您的客户经理，GGWP 会将其整合到您的特定 API 设置中。 * 在每次 API 调用期间——通过使用请求头，您也可以在每次发起 API 调用时输入一些自定义设置（详情请参见“用户名 API”部分）。这种方式存在一些限制，因为并非所有自定义元素都可以提供，而且更容易出错。 以下是可配置内容列表： * **主题**：可用主题包括暴力、色情内容、言语辱骂、身份仇恨、脏话、链接共享、毒品和自残。 * **过滤强度**：用户名 API 中的过滤强度配置基于“安全”这一总览维度。通常每个主题可选择 4 个值，但有少数例外。这 4 个值分别是： * 过滤强度 = “关闭” - 过滤器未启用，因此允许所有形式的有害内容。适合只面向成年人的环境，在这种环境中我们不希望施加任何限制。 * 过滤强度 = “低” - 仅过滤极端冒犯性内容，但允许中度和轻度有害内容通过。适合只面向成年人的环境。 * 过滤强度 = “中” - 过滤极端和中度有害内容，仅允许轻度有害内容通过。适合青少年环境，在这种环境中可容忍一些无伤大雅的有害内容。 * 过滤强度 = “高” - 过滤所有形式的有害内容。适合有儿童存在的环境。 * **自定义内容：** 如果您有自定义白名单或黑名单，并且其中包含您希望区别对待的术语，我们也可以将它们纳入您的特定 API 设置中。例如，如果有某些角色名您希望保留并防止用户在个人资料中使用，这会很有用。 ### **处理模式** 为支持不同的性能需求，用户名 API 提供两种处理模式。两者使用相同的类别和可配置设置，但在延迟和分析深度上有所不同。 **质量模式（默认）** 运行 GGWP 的完整模型，以获得最高检测准确率和更广泛的语言泛化能力。 * **延迟：** 中位数约 500–700 毫秒。 * **语言覆盖范围：** 支持显著更多的语言。 * **适用于：** 具有更严格安全政策或更年轻受众的社区，在这些场景下，尽量降低有害用户名漏过审核的风险非常重要。也适用于对延迟要求较低的离线检查，例如举报验证或对现有用户名进行周期性审核。 **性能模式** 使用精简模型，在优化低延迟的同时，仍覆盖用户名 API 支持的核心语言。 * **延迟：** 中位数约 100–150 毫秒 * **语言覆盖范围：** 支持“语言支持”部分中描述的标准语言集 * **适用于：** 实时用户名验证，以及需要快速响应时间的大批量工作流。 ### **语言支持** GGWP 用户名 API 当前支持以下语言： 阿拉伯语、中文、英语、法语、德语、印尼语、意大利语、日语、韩语、波兰语、葡萄牙语、俄语、西班牙语和土耳其语。 此外： * **质量模式** 将语言覆盖范围扩展到 **100+ 种语言**，这得益于其更为多样化的底层训练数据集。 * **性能模式** 针对上面列出的标准语言集进行了优化。 如果您需要额外语言支持，请联系您的客户经理，以查看可用性或即将发布的路线图项目。 ## 身份验证 GGWP 使用 API 密钥为下方列出的所有 API 端点中的授权用户提供安全访问。所有请求都必须在提供 API 密钥的同时附带以下 HTTP 请求头： `x-api-key: ` 每个 API 密钥： * 唯一标识您的平台/游戏 * 为本文档中列出的所有 API 提供访问权限 * 每秒可发起的请求数有特定速率限制，并且可能还会设置按月请求数量配额 * 应予以保密，不得与任何未授权的游戏/用户共享 * 一旦丢失，就必须重新生成新的密钥 请联系您的 GGWP 客户经理，以获取 API 密钥，并为您的游戏设置所需的正确速率限制。 ## 如何使用您的 API 密钥 以下是一个使用有效 API 密钥调用生产环境 API 端点的示例（本示例中已对密钥进行遮盖）： ```bash curl --request POST 'https://api.ggwp.com/username/v1/validate' \\ --header 'x-api-key: api_key' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" }' ``` 无效的 API 密钥将返回一个 `403` 返回代码。以下是使用无效 API 密钥的响应示例： ```bash < HTTP/2 403 < date: Thu, 18 Nov 2021 21:28:27 GMT < content-type: application/json < content-length: 23 < x-amzn-requestid: f4361ec6-71bc-478f-98cd-da0fe9df829b < x-amzn-errortype: ForbiddenException < x-amz-apigw-id: JBPLRHGjPHcFdbg= < * Connection #0 to host api.ggwp.com left intact {"message":"Forbidden"}* Closing connection 0 ``` ## 用户名 API \[ 基础 URL： `api.ggwp.com`] `POST` /username/v1/validate ### **描述** 此 API 端点会处理输入的用户名和用户 ID，以及一组用于有害内容过滤强度的可配置选项，并在 2 个层面返回信息： * 用户名详情——该用户名中有害内容存在情况和严重程度的指示，以及在发现有害内容时这些指示的置信度。 * 用户详情——基于用户名 API 调用历史记录与特定用户相关的上下文信息，包括最近被阻止的尝试。这使您能够对重复违规者触发不同操作。 ### **请求头** 配置设置可以通过您的 GGWP 账户设置提供（推荐），也可以通过 HTTP 请求头在每次请求时动态提供。
请求头必填描述
x-api-key是用于身份验证的 GGWP API 密钥。
Content-Type是必须设置为 application/json.
x-api-config可选经过 Base64 编码的 JSON 对象，其中包含每个请求的配置覆盖项（主题、过滤强度）。更多详情见下文。如果未提供，则应用默认设置或入驻时设置。
x-api-processing-mode可选为请求选择处理模式。可接受的值： quality （默认）或 performance.
**可配置主题（通过 `x-api-config`)** 下面列出了可配置主题及其支持的过滤强度值。这些值提供在通过 `x-api-config`: * **violence**：标记鼓励、赞美或威胁对个人或群体造成身体伤害或破坏的语言。这包括威胁、死亡诅咒以及对暴力行为的提及。支持的过滤强度值为： * off：此过滤器已关闭 * low：仅标记极端且图像化的暴力提及 * 示例：“getcancer”、“hopeyoudie”、“rapist” * medium：除上述情况外，还会标记其他不适合青少年或儿童受众的暴力行为提及 * 示例：“genocide”、“lynch”、“slaughter”、“torture”、“kidnapper” * high：除上述情况外，还会标记轻微暴力提及 * 示例：“kill”、“death”、“shooter”、“sniper”、“blood”、“murder” * **sexual\_content**：标记包含露骨性评论、暗示或不当/冒犯性提及的语言。这包括裸露描写、性行为提及或带有性暗示的语言。支持的过滤强度值为： * off：此过滤器已关闭 * low：标记极端性的性暴力提及 * 示例：“childmolester”、“daterape”、“gatorbait”、“sexoffender” * medium：除上述情况外，还会标记其他性行为提及以及任何中度露骨的性相关语言 * 示例：“suckmydick”、“penisfucker”、“pussy”、“blowjob”、“gangbang” * high：除上述情况外，还会标记被视为对儿童不适当的轻微性相关提及 * 示例：“boobs”、“cock”、“porn”、“sexy”、“butt” * **verbal\_abuse**：标记包含侮辱、人身攻击、贬损性言论或其他定向冒犯性语言的用户名。支持的过滤强度值为： * off：此过滤器已关闭 * low：仅标记高度冒犯和侮辱性术语 * 示例：“fuktard”、“schizo”、“mong”、“assmonkey” * medium：除上述情况外，还会标记其他形式的辱骂性语言或定向侮辱 * 示例：“bastard”、“douche”、“asshole”、“shitfucker”、“bitch” * high：除上述情况外，还会标记轻度冒犯性术语，并且最适合更年轻的受众 * 示例：“dummy”、“idiot”、“incel”、“braindead”、“smartass” * **identity\_hate**：标记包含基于宗教、族裔、国籍、种族、性别、性取向或其他身份因素，针对任何个人或群体的歧视性语言的用户名。支持的过滤强度值为： * off：此过滤器已关闭 * medium：仅过滤极端仇恨性辱骂 * 示例：“nigger”、“faggot”、“cunt”、“retard”、“chink”、“tranny”、“slut” * high：除上述情况外，还会标记那些经常与针对特定身份群体的更隐蔽偏见相关的身份术语 * 示例：“gay”、“homo”、“queer”、“nazi”、“lesbian” * **profanity**：标记包含淫秽、粗俗语言或脏话的用户名。支持的过滤强度值为： * off：此过滤器已关闭 * medium：标记更粗俗的脏话和冒犯性脏话 * 示例：“fuck”、“stfu”、“motherfucking”、“scumbag” * high：除上述情况外，还会标记轻度脏话 * 示例：“shit”、“dammit”、“ugly”、“stupid”、“noob”、“wtf”、“piss” * **link\_sharing**：标记包含外部链接的用户名，以防止用户分享不当网站、广告、诈骗或其他潜在有害内容。支持的过滤强度值为： * off：此过滤器已关闭 * medium：标记已知与常见不当或成人内容相关的 URL（例如：色情内容；赌博和其他非法活动；可能的网络钓鱼攻击） * high：标记所有 URL * **drugs**：标记包含对非法物质、吸毒行为或游戏环境中不适当的毒品文化提及的用户名。支持的过滤值为： * off：此过滤器已关闭 * on：此过滤器已开启，并会标记所有毒品相关提及 * 示例：“overdose”、“drunk”、“crack”、“alcohol”、“stoned”、“cocaine” * **self\_harm**：标记鼓励、赞美或暗示自伤、自杀或其他自我毁灭行为的用户名。支持的过滤值为： * off：此过滤器已关闭 * on：此过滤器已开启，并会阻止宣传有害行为 * 示例：“kys”、“suicide”、“cutyourself”、“endurlife” * **politics：** 标记包含政治提及的用户名，例如政党、政治人物或政治运动。支持的过滤值为： * off：此过滤器已关闭 * on：此过滤器已开启 * 示例：“obama”、“trump”、“liberal”、“BLM”、“socialist” * **religion：** 标记包含宗教相关提及的用户名，例如宗教、宗教人物，或通常与宗教相关的物品和地点。支持的过滤值为： * off：此过滤器已关闭 * on：此过滤器已开启 * 示例：“catholic”、“buddha”、“faith”、“pope”、“prophet”、“jewish” * **ideologies：** 标记包含有害意识形态提及的用户名。支持的过滤值为： * off：此过滤器已关闭 * on：此过滤器已开启 * 示例：“zionism”、“supremacy”、“caste”、“antivax”、“kkk”、“misogyny” * **controversial：** 标记包含争议人物、事件或群体提及的用户名。支持的过滤值为： * off：此过滤器已关闭 * on：此过滤器已开启 * 示例：“hitler”、“jeffreydahmer”、“hamas”、“covid19”、“slavery” **传递配置** 1. 示例 JSON（`config.json`) ```json { "violence": "off", "sexual_content": "low", "verbal_abuse": "medium", "identity_hate": "medium", "profanity": "high", "link_sharing": "high", "drugs": "off", "self_harm": "on", "politics": "on", "religion": "on", "ideologies": "on", "controversial": "on" } ``` 2. 将 JSON 进行 Base64 编码 ```bash base64 config.json ``` 3. 示例编码输出 
ewogICJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzZWxmX2hhcm0iOiAib24iCn0=
4. 示例 curl 请求 
curl --request POST 'https://api.ggwp.com/username/v1/validate' \\
     --header 'x-api-key:<API_KEY>' \\
     --header 'Content-Type: application/json' \\
     --header 'x-api-config: ewogICJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzZWxmX2hhcm0iOiAib24iCn0=' \\
     --header 'x-api-processing-mode: performance' \\
     --data-raw '{
       "username": "fuckyou123", 
       "user_id": "user001", 
       "timestamp": "2022-01-25 09:44:12"
     }'
**默认配置** 如果 `x-api-config` 请求头未提供： ```json { "violence": "high", "sexual_content": "high", "verbal_abuse": "high", "identity_hate": "high", "profanity": "high", "link_sharing": "high", "drugs": "on", "self_harm": "on", "politics": "on", "religion": "on", "ideologies": "on", "controversial": "on" } ``` 如果 `x-api-processing-mode` 未提供： ```json { "processing_mode": "quality" } ``` ### **参数** `请求体`：包含以下字段的字典：\n(*需要使用 utf-8 编码）* * **用户名：** 需要验证的用户名字符串。 * **用户 ID：** 提交用户名的用户唯一标识符。如果这是一个尚未创建 *user\_id* ，我们建议您使用下方所述的格式，其中 *sessionID* 可以基于任何能够识别该用户的活动，例如浏览器导航设置。 ```json user_id = "anonymous_sessionID" ``` * （可选） **时间戳：** 用户名创建时间 *YYYY-MM-DD HH:MM:SS* 格式，采用 UTC。如果未添加，则会用服务器端 UTC 时间戳替代。 示例 ```json { "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" } ``` 示例调用： ```bash curl --request POST 'https://api.ggwp.com/username/v1/validate' \\ --header 'x-api-key: api_key' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" }' ``` ### **输出** #### 200 响应 返回一个包含以下顶层字段的 JSON 对象：
username_details 提交用户名的用户名级审核结果。 * `username` — 提交用于审核的用户名。 * `flag` — `true` 如果该用户名被任何已配置的审核类别或自定义规则标记。 * `severity` — 分配给用户名的整体严重程度。可能的值： `none`, `low`, `medium`, `high`，以及 `custom`. * `custom` 当 GGWP 未标记该用户名，但该用户名与客户端自定义黑名单中的术语匹配时使用。 * `confidence` — 用户名级整体检测的置信度。可能的值： `none`, `low`, `medium`，或 `high`。这可用于调节审核行为： * 为减少误报，请将 `low` 置信度检测从自动执行中排除。 * 若要捕获更多潜在有害用户名，请包含 `low` 置信度检测，但代价是会标记更多临界用户名。 类别字段表示为该用户名检测到了哪些审核类别。这些字段为布尔值，且彼此并不互斥。一个用户名可能会被多个类别标记。 * `politics` — `true` 如果用户名匹配到政治内容信号。 * `controversial` — `true` 如果用户名匹配到争议内容信号。 * `sexual_content` — `true` 如果用户名匹配到色情内容信号。 * `violence` — `true` 如果用户名匹配到暴力相关信号。 * `profanity` — `true` 如果用户名匹配到脏话信号。 * `link` — `true` 如果用户名似乎包含 URL、域名或类似链接的内容。 * `self_harm` — `true` 如果用户名匹配到自残相关信号。 * `custom` — `true` 如果用户名匹配到客户端自定义黑名单术语。 * `religion` — `true` 如果用户名匹配到宗教相关内容信号。 * `identity_hate` — `true` 如果用户名匹配到基于身份的仇恨信号。 * `drugs` — `true` 如果用户名匹配到毒品相关内容信号。 * `verbal_abuse` — `true` 如果用户名匹配到侮辱或辱骂性语言信号。 * `ideologies` — `true` 如果用户名匹配到意识形态相关内容信号。
user_details 提交的用户级用户名审核历史 `user_id`. 此对象有助于识别短时间窗口内重复的用户名滥用行为，而不仅仅是孤立地评估当前用户名。 * `user_id` — 请求中提供的用户标识符。 * `recent_username_calls` — 过去 5 分钟内与该用户相关的用户名审核请求数。 * `recent_flagged` — 过去 5 分钟内与该用户相关且被标记的用户名审核请求数。 * `recent_flagged_usernames` — 过去 5 分钟内与该用户相关且被标记的用户名列表。
示例响应： ```json { "username_details": { "username": "fuckoff", "flag": true, "severity": "medium", "confidence": "high", "politics": false, "controversial": false, "sexual_content": false, "violence": false, "profanity": true, "link": false, "self_harm": false, "custom": false, "religion": false, "identity_hate": false, "drugs": false, "verbal_abuse": true, "ideologies": false }, "user_details": { "user_id": "123", "recent_username_calls": 8, "recent_flagged": 7, "recent_flagged_usernames": [ "yousuck", "yousuck", "fuckyou123", "fuckyouoff", "fuckyou123" ] } } ``` #### 400 响应 当请求无效时返回。 常见原因包括： * 无效的 JSON 输入 * 缺少必需字段 * 字段类型无效 * 请求正文格式错误 #### 403 响应 当 API 密钥缺失、无效或无权访问此端点时返回。 #### 500 响应 当由于内部服务器错误导致请求无法完成时返回。