# 图片检测调用接口 #### 功能介绍 调用图片检测能力接口的描述，具体格式：/v1/{project_id}/aiguard/image-detect #### URI POST /v1/{project_id}/aiguard/image-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 | 是 | Object | **参数解释：** 图片检测请求的数据体，包含待检测图片内容及相关元信息，服务端根据该对象中的信息执行相应的图片内容安全检测策略（如涉黄、涉政等）。 **约束限制：** 类型为 ImageMessage Object，需符合 JSON 对象格式。必填字段：role、content **取值范围：** 不涉及（对象类型，由内部子字段决定取值）。 **默认取值：** 不涉及。 | | extra | 否 | [TextDetectionExtra] object | **参数解释：** 受限公开字段，包含请求的扩展元信息，用于服务端进行安全运营分析、风险识别、恶意租户追踪，提升安全防护能力。 **约束限制：** 类型为Extra Object，需符合JSON对象格式.数组元素需包含 end_user 和 source_region 字段，结构为String对象 **取值范围：** 不涉及（对象类型，由内部子字段决定取值） **默认取值：** 不涉及（不传则不做安全增强分析）。 | 表4ImageMessage | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 是 | String | **参数解释：** 用于标识当前输入图片角色类型，便于服务端针对不同来源的图片执行差异化的内容安全检测策略。 **约束限制：** 字符串类型，仅支持预设的两个枚举值,区分大小写，必须为小写字母。 **取值范围：** user：用户输入请求内容;assistant：模型输出内容。 **默认取值：** user（不传时默认使用 user 进行输入检测）。 | | content | 是 | Array of [ImageContentItem] objects | **参数解释：** 待检测的内容列表，支持文本和图片 URL 的混合输入。服务端将按数组顺序遍历每个内容项，根据 type 字段识别内容类型（文本或图片），执行对应的内容安全检测策略（如文本敏感词过滤、图片涉黄/涉政/暴恐识别等），并返回各内容项的检测结果。 **约束限制：** 类型为 ImageContentItem 对象数组，需符合 JSON 数组格式 **取值范围：** 如果有多个图片的ImageContentItem对象，目前只检测匹配到的第一个 **默认取值：** 不涉及。 | 表5ImageContentItem | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 是 | String | **参数解释：** 内容类型标识，用于指定当前检测项的媒体类型。服务端通过该字段识别检测项是文本还是图片，从而选择对应的检测策略和解析方式。 **约束限制：** 字符串类型；仅支持预设枚举值 image_url **取值范围：** image_url（图片 URL 类型） **默认取值：** 不涉及。 | | image_url | 是 | [image_url] object | **参数解释：** 图片详细信息对象，用于封装待检测图片的访问地址。服务端通过该对象中的 url 字段获取图片内容并执行安全检测。 **约束限制：** 类型为 ImageUrlObject，需符合 JSON 对象格式；必填字段：url； **取值范围：** 不涉及（对象类型，由内部 url 字段决定取值）。 **默认取值：** 不涉及。 | 表6image_url | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | url | 是 | String | **参数解释：** 图片的 Base64 编码数据（Data URL 格式），用于传递待检测的图片内容。 **约束限制：** 字符串类型；Base64 编码数据需为有效编码，否则服务端将返回解码失败错误 **取值范围：** 符合 Data URL 规范的 Base64 字符串。 **默认取值：** 不涉及。 | 表7TextDetectionExtra | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | request_id | String | **参数解释：** 本次请求的唯一标识符，用于链路追踪、日志关联和问题排查。建议调用方在日志中保存该值，当遇到异常或需要技术支持时，提供该 ID 以便平台方快速定位问题。 **取值范围：** 长度：1\~64 字符；字母（a-z，A-Z）、数字（0-9）及中划线（-）组合，全局唯一 | | maf_engine | String | **参数解释：** 本次检测所使用的引擎ID标识符，用于标识服务端实际执行内容安全检测的引擎实例或引擎版本，便于问题排查和引擎效果评估。 **取值范围：** 默认为cllmfw | | result | [ImageDetectionResult] object | **参数解释：** 图片检测结果对象，包含本次图片内容安全检测的详细结论。调用方可根据该字段的值进行后续业务处理（如放行、拦截、替换等）。 **取值范围：** 包含以下子字段suggestion（String）：检测建议、risk_types（Array\[String\]）：命中的风险类型列表、hit_details（Array\[ImageDetectionResultDetail\]）：检测详情和replacement（String）：脱敏替换内容。 | 表9ImageDetectionResult | 参数 | 参数类型 | 描述 | |:---|:---|:---| | suggestion | String | **参数解释：** 检测建议，表示服务端对图片内容安全性的综合判定结论。 **取值范围：** pass：通过，未检测到异常信息，内容安全，建议放行；block：违规，检测到异常信息，内容不安全，建议拦截 | | risk_types | Array of strings | **参数解释：** 命中的风险类型列表，表示图片内容触发的具体风险类别。 **取值范围：** compliance：检测到合规攻击, inject：检测到注入攻击 | | hit_details | Array of [ImageDetectionResultDetail] objects | **参数解释：** 检测详情列表，提供命中的具体风险详细信息。 **取值范围：** 数组类型，每个元素包含以下子字段：risk_type（String）：风险类型、sub_risk_type（String）：风险子类型、prob（Number）：置信度分数（0\~1）、segments（Array）：命中片段信息、risk_source（String）：风险来源。 | | replacement | String | **参数解释：** 脱敏后的替换内容，当服务端检测到违规内容且业务方已配置脱敏策略时，返回建议的替换文本。 **取值范围：** 长度：0\~255 字符（空字符串表示无替换内容）；格式：替换后的文本内容，包含脱敏处理后的安全文本 | 表10ImageDetectionResultDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | risk_type | String | **参数解释：** 命中的风险类型，标识该条检测详情对应的主要风险类别。 **取值范围：** compliance：检测到合规攻击, inject：检测到注入攻击 | | sub_risk_type | Array of strings | **参数解释：** 命中的风险子类型列表，提供比 risk_type 更细粒度的风险分类信息。 **取值范围：** 数组元素由引擎动态决定，不同 risk_type 对应不同的子类型。 | | prob | Float | **参数解释：** 置信度分数，表示服务端对该条风险判定结果的置信程度。 **取值范围：** 浮点数，0.0-1.0包含边界值，命中词库时默认为1.0 | | segments | Array of [SegmentInfo] objects | **参数解释：** 敏感词内容检测的详细情况，包含命中的敏感词具体信息。 **取值范围：** 数组类型，包含以下子字段：segment、category、position、lexicon_id、lexicon_type | | risk_source | String | **参数解释：** 风险来源，标识该风险是由哪个检测维度触发的，便于调用方了解风险判定的具体依据。 **取值范围：** 如果是图片文本导致风险问题为ocr，如果是图片语义导致的风险问题为content。 | 表11SegmentInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | segment | String | 命中的风险片段 | | category | String | 命中的内置词库或者文本向量库类别以及自定义词库为词库的名称。 | | position | Array of integers | 命中词库时生效，命中的风险片段在文本中的起始位置，从0开始 | | lexicon_id | String | 命中自定义词库时生效，返回对应词库ID | | lexicon_type | Integer | 命中自定义词库时生效，0：豁免，1：违规 | **状态码：400** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | request_id | String | 本次请求的唯一标识，用于问题排查，建议保存 | | maf_engine | String | 引擎id信息 | | error | [ErrorBody] object | 请求出问题时返回的字段 | | error_code | String | **参数解释：** 错误码，用于定义具体的错误类型，便于调用方根据错误码进行异常处理、日志分类和问题排查 **取值范围：** 长度为8,例如：AIGUARD.0001 | | error_msg | String | **参数解释：** 错误描述信息，提供可读的错误原因说明，便于调用方定位问题和向用户展示友好的错误提示。 **取值范围：** 长度：2\~255字符，格式：中文或英文描述 | 表13ErrorBody | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码，长度8 | | error_msg | String | 错误描述 | #### 请求示例 ``` { "app_id" : "xxxx", "message" : { "role" : "user", "content" : [ { "type" : "image_url", "image_url" : { "url" : "data:image/png;base64,XXX" } } ] } } ``` #### 响应示例 无 #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 图片检测成功响应 | | 400 | 检测异常或输入异常 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-waf/ErrorCode.html)。