# API接入 本文档介绍API接入的方法。 #### 文本检测API说明 您可以调用该接口创建文本内容检测任务。 - **业务接口：**POST https://{endpoint}/v1/{project_id}/aiguard/text-detect - **支持的地域及接入地址**：西南-贵阳一 #### 请求参数 表1请求path参数 | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | v1 | String | 是 | API接口版本。 | | project_id | String | 是 | 如使用op账号调用，则使用op账号项目ID信息；如使用最终租户账号调用，则使用最终租户账号项目ID信息。 | | aiguard | String | 是 | API接口组件名称。 | | text-detect | String | 是 | API接口调用类型。 | 表2请求header参数 | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | Source-Signature | String | 是 | 业务方签名，用于标示业务方身份，华为云内部服务调用时必传该字段。 | | Content-Type | String | 否 | 文本请求默认为application/json。 | 表3TextDetectionReq请求体 | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | app_id | String | 是 | 应用ID，用于区分配置。 | | message | [表5] | 是 | 文本检测请求数据体。 | | history | Array of [表5] | 否 | 对话的历史数据，最多支持10轮。列表排序越前面的表示越早期的对话。越后面的表示越接近现在的对话。 | | extra | [表4] | 否 | 受限公开字段。 | 表4Extra | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | end_user | String | 否 | 最终租户projectid（服务使用Op账号调用时，传此字段，供安全运营、识别恶意最终租户）。 | | source_region | String | 否 | 最终租户调用的原始region（供安全运营）。 | 表5Message | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | role | String | 是 | 输入字段类型，可选值如下： - user（默认）：用户输入请求内容 - assistant：模型输出内容 - system：系统提示词 对于响应或多轮对话，以最新的内容为准。 | | content | String | 是 | 检测文本，支持（1\~262144），超过256K长度取后256K进行检测。 如果超过这个长度，AI安全护栏会截断，只取后面的部分。 | #### 响应参数 返回状态码：200 表6TextDetectionResponse | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | request_id | String | 是 | 本次请求的唯⼀标识，⽤于问题排查，建议保存。 | | maf_engine | String | 是 | 厂商信息，默认为cllmfw。 | | result | 表1-10 TextDetectionResult | 否 | 请求成功时表示调用结果。 请求失败时无此字段。 | | error | 表1-15 ErrorBody | 否 | 请求出问题时返回的字段 请求成功无此字段。 | 表7TextDetectionResult | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | suggestion | String | 是 | 审核结果是否通过。 配置的异常处理动作： 观察、脱敏、拦截 - pass：未检测到异常信息。任何观察(log)和脱敏(desensitize)都在pass类别中。 - block：检测到异常信息。 | | risk_types | Array of String | 是 | 命中的风险类型，例如合规攻击、注入攻击。 | | hit_details | Array of [表8] | 是 | 检测详情。 | | replacement | String | 否 | 配置脱敏时生效，当前仅支持违规词库脱敏。(白词库，语义模型当前不用脱敏) 若没有配置脱敏，返回空字段。 | 表8TextDetectionResultDetail | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | risk_type | String | 是 | 命中的风险类型，例如合规攻击、注入攻击。 | | sub_risk_type | Array of String | 是 | 命中的风险子类型， 支持合规检测（例如）的标签、自定义词库的名字。更多信息请参见[功能介绍](https://support.huaweicloud.com/usermanual-waf/waf_07_00015_1.html#waf_07_00015_1__section19587616151618)。 | | prob | Float | 是 | 置信度分数，命中词库时默认为1.0。 | | segments | Array of [表9] | 否 | 用于词库。 单个词库命中所有风险片段信息，如果命中了语义算法模型，则会返回一个空的列表。 | 表9SegmentInfo | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | segment | String | 是 | 命中的风险片段。 | | category | String | 是 | 命中的词库。自定义词库为词库的名称，内置词库为词库的类别。 | | position | Array of Integer | 否 | 命中词库时生效。 命中的风险片段在文本中的起始位置，从0开始。 否则无字段。 | | lexicon_id | String | 否 | 命中自定义词库时生效，返回对应词库ID。 否则无字段。 | | lexicon_type | String | 否 | 0：豁免。 1：违规。 命中自定义词库时生效，返回自定义词库是豁免还是违规。 | 表10ErrorBody | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | error_code | String | 是 | 错误码 长度：8 | | error_msg | String | 是 | 错误描述 最小长度：2 最大长度：512 | #### 图片检测API说明 您可以调用该接口创建图片内容检测任务。 - **业务接口：**POST https://{endpoint}/v1/v1/{project_id}/aiguard/image-detect - **支持的地域及接入地址**：西南-贵阳一 #### 请求参数 表11请求path参数 | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | v1 | String | 是 | API接口版本。 | | project_id | String | 是 | 如使用op账号调用，则使用op账号项目ID信息；如使用最终租户账号调用，则使用最终租户账号项目ID信息。 | | aiguard | String | 是 | API接口组件名称。 | | image-detect | String | 是 | API接口调用类型。 | 表12请求header参数 | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | Source-Signature | String | 是 | 业务方签名，用于标示业务方身份，华为云内部服务调用时必传该字段。 | | Content-Type | String | 否 | 文本请求默认为application/json。 | 表13PicDetectionReq请求体 | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | app_id | String | 是 | 应用ID，用于区分配置。 | | message | [表15] | 是 | 图片检测请求数据体。 | | extra | [表14] | 否 | 受限公开字段。 | 表14Extra | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | end_user | String | 否 | 最终租户projectid（服务使用Op账号调用时，传此字段，供安全运营、识别恶意最终租户）。 | | source_region | String | 否 | 最终租户调用的原始region（供安全运营）。 | 表15Message | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | role | String | 是 | 输入字段类型，可选值如下： - user（默认）：用户输入请求内容 - assistant：模型输出内容 - system：系统提示词 对于响应或多轮对话，以最新的内容为准。 | | content | String | 是 | \[{"type": "text", "text": "图里有什么？"}, {"type": "image_url", "image_url": {"url": ""} }\] 检测的图片内容，匹配first(item in list where item.type == "image_url").image_url.url 如果有多个图片的url，目前只检测匹配到的第一个。 说明： 仅支持base64，且url里面base64的格式也是固定的data:xxx;base64,xxx，例如：（data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAA） | #### 响应参数 表16ImageDetectionResponse | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | request_id | String | 是 | 本次请求的唯⼀标识，⽤于问题排查，建议保存。 | | maf_engine | String | 是 | 厂商信息，默认为cllmfw。 | | result | [表17] | 否 | 请求成功时表示调用结果。 请求失败时无此字段。 | | error | [表20] | 否 | 请求出问题时返回的字段 请求成功无此字段。 | 表17ImageDetectionResult | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | suggestion | String | 是 | 审核结果是否通过。 配置的异常处理动作： 观察、脱敏、拦截。 - pass：未检测到异常信息。任何观察(log)和脱敏(desensitize)都在pass类别中。 - block：检测到异常信息。 | | risk_types | Array of String | 是 | 命中的风险类型，例如合规攻击、注入攻击。 | | hit_details | Array of [表18] | 是 | 检测详情。 | | replacement | String | 否 | 配置脱敏时生效，当前仅支持违规词库脱敏。(白词库，语义模型当前不用脱敏)。 若没有配置脱敏，返回空字段。 | 表18ImageDetectionResultDetail | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | risk_type | String | 是 | 命中的风险类型，例如合规攻击、注入攻击。 | | sub_risk_type | Array of String | 是 | 命中的风险子类型， 支持合规检测（例如）的标签、自定义词库的名字。更多信息请参见[功能介绍](https://support.huaweicloud.com/usermanual-waf/waf_07_00015_1.html#waf_07_00015_1__section19587616151618)。 | | prob | Float | 是 | 置信度分数，命中词库时默认为1.0。 | | segments | Array of [表19] | 否 | 用于词库。 单个词库命中所有风险片段信息，如果命中了语义算法模型，则会返回一个空的列表。 | | risk_source | String | 否 | 只针对图片。 用于反映是图片文本的风险还是图片语义的风险。 | 表19SegmentInfo | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | segment | String | 是 | 命中的风险片段。 | | category | String | 是 | 命中的词库。自定义词库为词库的名称，内置词库为词库的类别。 | | position | Array of Integer | 否 | 命中词库时生效。 命中的风险片段在文本中的起始位置，从0开始。 否则无字段。 | | lexicon_id | String | 否 | 命中自定义词库时生效，返回对应词库ID。 否则无字段。 | | lexicon_type | String | 否 | 0：豁免 1：违规 命中自定义词库时生效，返回自定义词库是豁免还是违规。 | 表20ErrorBody | 名称 | 类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | error_code | String | 是 | 错误码，长度为8。 | | error_msg | String | 是 | 错误描述。最小长度为2，最大长度为512。 |