文档首页/图像识别 Image/API参考/API/主体识别-RunImageMainObjectDetection
更新时间：2025-12-08 GMT+08:00
查看PDF
分享

主体识别-RunImageMainObjectDetection

功能介绍

用户传入图片通过后台算法判断图片主体，并返回主体坐标，具体识别的主体请参考应用场景。

前提条件

  • 使用主体识别服务之前需要您完成服务申请和认证鉴权。
  • 图像识别服务属于公有云服务，线上用户资源共享，如果需要多并发请求，请提前联系我们。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

POST /v3/{project_id}/image/main-object-detection

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

用户的项目ID。获取方法请参见获取项目ID和名称。

约束限制：

不涉及。

取值范围：

只能由英文字母和数字组成，且长度为[1-64]个字符。

默认取值：

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释：

用户Token。用于获取操作API的权限。获取方法请参见获取Token接口，响应消息头中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服务的访问权限。

约束限制：

  • 接口响应时间依赖于图片的下载时间，如果图片下载时间过长，会返回接口调用失败。
  • 请保证被检测图片所在的存储服务稳定可靠，推荐使用OBS服务存储图片数据。
  • lmage不支持跨区域OBS，OBS的区域需要和服务保持一致。

取值范围：

不涉及。

默认取值：

不涉及。

threshold

否

Float

参数解释：

置信度的阈值（0~100），低于此置信数的标签，将不会返回。

约束限制：

不涉及。

取值范围：

0-100。

默认取值：

30。

响应参数

状态码： 200

表4 result

参数

参数类型

描述

result

Array of ImageMainObjectDetectionInstance objects

参数解释：

主体列表集合。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表5 ImageMainObjectDetectionInstance

参数

参数类型

描述

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

参数解释：

调用失败时的错误码，具体请参见错误码。

调用成功时无此字段。

取值范围：

不涉及。

error_msg

String

参数解释：

调用失败时的错误信息。

调用成功时无此字段。

取值范围：

不涉及。

请求示例

  • “endpoint”即调用API的请求地址，不同服务不同区域的“endpoint”不同，具体请参见终端节点。

    例如，服务部署在“华北-北京四”区域的“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和名称。

  • 方式一：使用图片的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

失败响应结果。

错误码

请参见错误码。

父主题：API

相关文档