文档首页/图像识别 Image/API参考/API/图像标签（V2）-RunImageTagging
更新时间：2025-12-08 GMT+08:00
查看PDF
分享

图像标签（V2）-RunImageTagging

功能介绍

自然图像的语义内容非常丰富，一个图像包含多个标签内容，图像标签服务准确识别自然图片中数百种场景、上千种通用物体及其属性，让智能相册管理、照片检索和分类、基于场景内容或者物体的广告推荐等功能更加直观。使用时用户发送待处理图片，返回图像标签内容及相应置信度。

前提条件

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

调试

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

URI

URI格式

POST /v2/{project_id}/image/tagging

表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的区域需要和服务保持一致。

取值范围：

不涉及。

默认取值：

不涉及。

language

否

String

参数解释：

语言类型。

约束限制：

不涉及。

取值范围：

  • zh：返回标签的语言类型为中文。
  • en：返回标签的语言类型为英文。

默认取值：

默认值为zh。

threshold

否

Float

参数解释：

置信度的阈值。

约束限制：

不涉及。

取值范围：

取值范围是0-100。

默认取值：

默认值为60。

limit

否

Integer

参数解释：

最多返回的标签数。

约束限制：

不涉及。

取值范围：

最多150个，最少为1个。

默认取值：

不涉及。

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

result

result object

参数解释：

调用成功时为图像标签内容。

调用失败时无此字段。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表5 result

参数

参数类型

描述

tags

Array of ImageTaggingItemBody objects

参数解释：

标签列表集合。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表6 ImageTaggingItemBody

参数

参数类型

描述

confidence

String

参数解释：

置信度，将Float型置信度转为String类型返回，取值范围：0-100。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

type

String

参数解释：

标签的类别。

约束限制：

不涉及。

取值范围：

有以下三种类别：

  • object：实体标签
  • scene：场景标签
  • concept：概念标签

默认取值：

不涉及。

tag

String

参数解释：

标签名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

i18n_tag

i18n_tag object

参数解释：

标签的多种语言输出。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

i18n_type

i18n_type object

参数解释：

标签类别的多种语言输出。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

instances

Array of ImageTaggingInstance objects

参数解释：

目标检测框信息，为空则表示没有目标检测框。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表7 i18n_tag

参数

参数类型

描述

zh

String

参数解释：

中文标签。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

en

String

参数解释：

英文标签。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表8 i18n_type

参数

参数类型

描述

zh

String

参数解释：

中文标签类别。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

en

String

参数解释：

英文标签类别。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表9 ImageTaggingInstance

参数

参数类型

描述

bounding_box

BoundingBoxFloat Object

参数解释：

目标检测框位置信息。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

confidence

String

参数解释：

检测标签置信度，将Float型置信度转为String类型返回，Float取值范围（0~100）。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

表10 BoundingBoxFloat

参数

参数类型

描述

width

Double

参数解释：

检测框区域宽度。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

height

Double

参数解释：

检测框区域高度。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

top_left_x

Double

参数解释：

检测框左上角到垂直轴距离。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

top_left_y

Double

参数解释：

检测框左上角到水平轴距离。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

状态码： 400

表11 响应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/tagging”，“project_id”为项目ID，获取方法请参见获取项目ID和名称。

  • 方式一：使用图片的BASE64编码，对待处理图片返回图像标签内容及相应置信度，返回标签的语言类型为中文，置信度的阈值为70。 
    POST https://{endpoint}/v2/{project_id}/image/tagging

{
  "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA...",
  "url" : "",
  "language" : "zh",
  "limit" : 5,
  "threshold" : 70.0
}
  • 方式二：使用图片URL，对待处理图片返回图像标签内容及相应置信度，返回标签的语言类型为中文，置信度的阈值为70。 
    POST https://{endpoint}/v2/{project_id}/image/tagging

{
  "image" : "",
  "url" : "https://BucketName.obs.myhuaweicloud.com/ObjectName",
  "language" : "zh",
  "limit" : 5,
  "threshold" : 70.0
}

响应示例

状态码： 200

成功响应结果

{
  "result" : {
    "tags" : [ {
      "confidence" : "37.51",
      "instances" : [ {
        "confidence" : "92.38",
        "bounding_box" : {
          "height" : 133.32496056189905,
          "top_left_x" : 53.134917332575874,
          "top_left_y" : 254.21347984900842,
          "width" : 117.5866567171537
        }
      } ],
      "tag" : "人",
      "i18n_tag" : {
        "en" : "person",
        "zh" : "人"
      },
      "type" : "人类",
      "i18n_type" : {
        "en" : "Human",
        "zh" : "人类"
      }
    } ]
  }
}

状态码： 400

失败响应结果

{
  "error_code" : "AIS.0005",
  "error_msg" : "The service does not exist."
}

状态码

状态码

描述

200

成功响应结果。

400

失败响应结果。

错误码

请参见错误码。

父主题：API

相关文档