# 文本检测调用接口 #### 功能介绍 调用文本检测能力接口的描述，具体格式：/v1/{project_id}/aiguard/text-detect #### URI POST /v1/{project_id}/aiguard/text-detect 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 用户所属项目的唯一标识ID，用于关联请求与对应的项目资源。 **约束限制：** 32位UUID格式，仅支持小写字母a-f与数字0-9组合，必须为当前用户有权限的有效项目ID。 **取值范围：** 如使用op账号调用，则使用op账号项目id信息；如使用最终租户账号调用，则使用最终租户账号项目id信息。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Source-Signature | 是 | String | **参数解释：** 业务方签名，用于验证请求方的合法身份确保服务端仅处理来自已授权业务方合法请求，华为云内部服务调用时必传该字段。 **约束限制：** 华为云内部服务调用时必传该字段。HMAC-SHA256加密算法生成，需包含时间戳及业务方唯一标识，以防重放攻击且区分大小写 **取值范围：** 由HMAC-SHA256加密算法决定，无固定取值枚举。 **默认取值：** 不涉及。 | | Content-Type | 否 | String | **参数解释：** 用于指定请求体的媒体类型（MIME Type），告知服务端如何解析请求体中的数据格式，确保服务端正确反序列化请求内容。 **约束限制：** 字符串类型，必须为标准的MIME Type格式，需与请求体实际格式保持一致，否则服务端将返回解析错误。 **取值范围：** 文本请求默认为application/json。 **默认取值：** application/json。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | app_id | 是 | String | **参数解释：** 应用ID，用于标识调用方的应用身份，服务端根据该ID获取该应用下用户配置的自定义策略，实现不同应用的差异化处理。 **约束限制：** 字符串类型，长度1-36字符，仅支持字母、数字、下划线、中划线,必须为当前用户已创建的有效应用ID。 **取值范围：** 1\~64位字母、数字、下划线、中划线组合。 **默认取值：** 不涉及。 | | message | 是 | [TextDetectionMessage] object | **参数解释：** 文本检测请求的数据体，包含待检测文本的具体内容及相关元信息，服务端根据该对象中的信息执行相应的文本检测策略。 **约束限制：** 类型为Message Object，需符合JSON对象格式。必填字段：role、content **取值范围：** 不涉及（对象类型，由内部子字段决定取值）。 **默认取值：** 不涉及。 | | history | 否 | Array of [TextDetectionMessage] objects | **参数解释：** 历史对话信息，用于提供上下文关联，帮助服务端理解当前对话来龙去脉，实现多轮对话场景下连贯检测与响应，提升检测准确率。 **约束限制：** 类型为Message Object数组，需符合JSON数组格式.数组元素需包含 role 和 content 字段，结构同 message 对象 **取值范围：** 对话的历史数据，最多支持10轮 **默认取值：** 不涉及（不传或传空数组 \[\] 表示无历史对话）。 | | extra | 否 | [TextDetectionExtra] object | **参数解释：** 受限公开字段，包含请求的扩展元信息，用于服务端进行安全运营分析、风险识别、恶意租户追踪，提升安全防护能力。 **约束限制：** 类型为Extra Object，需符合JSON对象格式.数组元素需包含 end_user 和 source_region 字段，结构为String对象 **取值范围：** 不涉及（对象类型，由内部子字段决定取值） **默认取值：** 不涉及（不传则不做安全增强分析）。 | 表4TextDetectionMessage | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 是 | String | **参数解释：** 用于标识当前输入文本角色类型，便于服务端针对不同来源的文本执行差异化的内容安全检测策略。 **约束限制：** 符串类型，仅支持预设的两个枚举值,区分大小写，必须为小写字母。 **取值范围：** user：用户输入请求内容;assistant：模型输出内容。 **默认取值：** user（不传时默认使用 user 进行输入检测）。 | | content | 是 | String | **参数解释：** 待检测的原始文本内容，服务端将对该字段中的文本执行内容安全检测，并返回对应的检测结果。 **约束限制：** 字符串类型；长度范围：1\~8192字符（含边界值);支持中英文、数字及常见标点符号；超过8192字符时，服务端自动截取前8192个字符进行检测，超出部分将被忽略； **取值范围：** 1\~8192字符的文本内容 **默认取值：** 不涉及。 | 表5TextDetectionExtra | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | end_user | 否 | String | **参数解释：** 最终租户的项目ID，用于标识请求所代理的实际终端用户所属项目。当服务使用Op（运营/管理员）账号调用接口时，通过该字段传递最终租户身份信息，供服务端进行安全运营分析、审计日志记录及识别恶意最终租户，便于平台对异常行为进行追溯和管控 **约束限制：** 字符串类型；固定32位UUID格式；仅支持小写字母（a-f）与数字（0-9）组合；必须为平台已存在的有效项目ID；该字段仅在Op账号调用时生效，普通租户账号调用时传入将被忽略或报错 **取值范围：** 固定32位十六进制字符（a-f0-9），示例：*a1b2c3d4e5f678901234567890abcdef* **默认取值：** 不涉及。 | | source_region | 否 | String | **参数解释：** 最终租户调用接口时所处的地理区域标识，用于标识请求的实际来源地域。服务端通过该字段进行安全运营分析（如地域维度的流量监控、风险识别、恶意租户追踪、异常行为检测等），便于平台针对不同地域实施差异化的安全策略。 **约束限制：** 字符串类型；长度范围：1\~32字符；该字段仅在 Op 账号调用时生效（与 end_user 配合使用），普通租户账号调用时传入将被忽略或报错 **取值范围：** 标准地域代码 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | request_id | String | 本次请求的唯一标识，用于问题排查，建议保存 | | maf_engine | String | 引擎id信息 | | result | [TextDetectionResult] object | 请求成功时表示调用结果 | 表7TextDetectionResult | 参数 | 参数类型 | 描述 | |:---|:---|:---| | suggestion | String | 审核结果是否通过。pass：未检测到异常信息；block：检测到异常信息 | | risk_types | Array of strings | 风险类型。compliance：检测到合规攻击, inject：检测到注入攻击 | | hit_details | Array of [TextDetectionResultDetail] objects | 检测详情 | | replacement | String | 配置脱敏时生效，当前仅支持违规词库脱敏。若没有配置脱敏，返回空字段。 | 表8TextDetectionResultDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | risk_type | String | 风险类型。compliance：检测到合规攻击, inject：检测到注入攻击 | | sub_risk_type | Array of strings | 命中的风险子类型。 | | prob | Float | 置信度分数，命中词库时默认为1.0 | | segments | Array of [TextDetectionSegmentInfo] objects | 敏感词内容检测的详细检测情况 | 表9TextDetectionSegmentInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | segment | String | 命中的风险片段 | | category | String | 命中的内置词库或者文本向量库类别以及自定义词库为词库的名称。 | | position | Array of integers | 命中词库时生效，命中的风险片段在文本中的起始位置，从0开始 | | lexicon_id | String | 命中自定义词库时生效，返回对应词库ID | | lexicon_type | Integer | 命中自定义词库时生效，0：豁免，1：违规 | **状态码：400** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | request_id | String | 本次请求的唯一标识，用于问题排查，建议保存 | | maf_engine | String | 引擎id信息 | | error | [TextDetectionErrorBody] object | 请求出问题时返回的字段 | | error_code | String | 错误码，用于定义具体错误类型（例如：AIGUARD.0001） | | error_msg | String | 错误描述信息，说明具体的失败原因 | 表11TextDetectionErrorBody | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码 | | error_msg | String | 错误描述 | #### 请求示例 无 #### 响应示例 无 #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 文本检测成功响应 | | 400 | 检测异常或输入异常 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-waf/ErrorCode.html)。