# 主体识别-RunImageMainObjectDetection #### 功能介绍 用户传入图片通过后台算法判断图片主体，并返回主体坐标，具体识别的主体请参考[应用场景](https://support.huaweicloud.com/productdesc-image/image_01_0003.html)。 #### 前提条件 - 使用主体识别服务之前需要您完成[服务申请](https://support.huaweicloud.com/api-image/image_03_0018.html)和[认证鉴权](https://support.huaweicloud.com/api-image/image_03_0003.html)。 - 图像识别服务属于公有云服务，线上用户资源共享，如果需要多并发请求，请提前[联系我们](https://www.huaweicloud.com/service/contact.html)。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=Image&api=RunImageMainObjectDetection)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### URI POST /v3/{project_id}/image/main-object-detection 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 用户的项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-image/image_03_0035.html)。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母和数字组成，且长度为\[1-64\]个字符。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** 用户Token。用于获取操作API的权限。获取方法请参见[获取Token接口](https://support.huaweicloud.com/api-image/image_03_0003.html)，响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image | 否 | String | **参数解释：** 与url二选一。 图像数据，base64编码。 **约束限制：** 不涉及。 **取值范围：** 要求base64编码后大小不超过10M，最短边至少1px，最长边最大10000px，支持JPEG/PNG/BMP/WEBP格式。 **默认取值：** 不涉及。 | | url | 否 | String | **参数解释：** 与image二选一。 图片的URL路径，目前支持： - 公网HTTP/HTTPS URL - OBS提供的URL，使用OBS数据需要进行授权。包括对服务授权、临时授权、匿名公开授权。详情参见[配置OBS服务的访问权限](https://support.huaweicloud.com/api-image/image_03_0037.html)。 **约束限制：** - 接口响应时间依赖于图片的下载时间，如果图片下载时间过长，会返回接口调用失败。 - 请保证被检测图片所在的存储服务稳定可靠，推荐使用OBS服务存储图片数据。 - lmage不支持跨区域OBS，OBS的区域需要和服务保持一致。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | threshold | 否 | Float | **参数解释：** 置信度的阈值（0\~100），低于此置信数的标签，将不会返回。 **约束限制：** 不涉及。 **取值范围：** 0-100。 **默认取值：** 30。 | #### 响应参数 **状态码： 200** 表4result | 参数 | 参数类型 | 描述 | |:---|:---|:---| | result | Array of [ImageMainObjectDetectionInstance] objects | **参数解释：** 主体列表集合。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5ImageMainObjectDetectionInstance | 参数 | 参数类型 | 描述 | |:---|:---|:---| | label | String | **参数解释：** 主体的类别。 **约束限制：** 不涉及。 **取值范围：** - main_object_box（主要主体）。 - bounding_box（边缘主体）。 **默认取值：** 不涉及。 | | location | location object | **参数解释：** 目标检测框位置信息，包括4个值: - width:检测框区域宽度。 - height:检测框区域高度。 - top_left_x:检测框左上角到垂直轴距离。 - top_left_y:检测框左上角到水平轴距离。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | confidence | String | **参数解释：** 主体框的置信度。将Float型置信度转为String类型返回，Float取值范围(0\~100)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | **状态码： 400** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 调用失败时的错误码，具体请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。 调用成功时无此字段。 **取值范围：** 不涉及。 | | error_msg | String | **参数解释：** 调用失败时的错误信息。 调用成功时无此字段。 **取值范围：** 不涉及。 | #### 请求示例 ![](https://support.huaweicloud.com/api-image/public_sys-resources/note_3.0-zh-cn.png) - "endpoint"即调用API的请求地址，不同服务不同区域的"endpoint"不同，具体请参见[终端节点](https://support.huaweicloud.com/api-image/image_03_0032.html)。 例如，服务部署在"华北-北京四"区域的"endpoint"为"image.cn-north-4.myhuaweicloud.com"，请求URL为"https://image.cn-north-4.myhuaweicloud.com/v2/{project_id}}/image/main-object-detection"，"project_id"为项目ID，获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-image/image_03_0035.html)。 - 方式一：使用图片的BASE64编码，判断图片主体并返回主体坐标，置信度的阈值为30。 ``` POST https://{endpoint}/v3/{project_id}image/main-object-detection { "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA...", "url" : "", "threshold" : 30 } ``` - 方式二：使用图片URL，判断图片主体并返回主体坐标，置信度的阈值为30。 ``` POST https://{endpoint}/v3/{project_id}image/main-object-detection { "image" : "", "url" : "https://BucketName.obs.myhuaweicloud.com/ObjectName", "threshold" : 30 } ``` #### 响应示例 **状态码： 200** 成功响应结果 ``` { "result" : [ { "label" : "bounding_box", "location" : { "height" : 133.32, "top_left_x" : 53.13, "top_left_y" : 254.21, "width" : 117.58 }, "confidence" : "92.38" }, { "label" : "main_object_box", "location" : { "height" : 261.32, "top_left_x" : 256.13, "top_left_y" : 85.21, "width" : 139.58 }, "confidence" : "66.38" } ] } ``` **状态码： 400** 失败响应结果 ``` { "error_code" : "AIS.0005", "error_msg" : "The service does not exist." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 成功响应结果。 | | 400 | 失败响应结果。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。