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

主体识别

功能介绍

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

前提条件

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

调试

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

URI

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

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

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

请求参数

表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存储。

threshold

否

Float

置信度的阈值(0~100)，低于此置信数的检测结果，将不会返回。

默认值:30，最小值:0，最大值:100。

响应参数

状态码： 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

相关文档