# 图像标签（V2）-RunImageTagging #### 功能介绍 自然图像的语义内容非常丰富，一个图像包含多个标签内容，图像标签服务准确识别自然图片中数百种场景、上千种通用物体及其属性，让智能相册管理、照片检索和分类、基于场景内容或者物体的广告推荐等功能更加直观。使用时用户发送待处理图片，返回图像标签内容及相应置信度。 #### 前提条件 - 使用图像标签服务之前需要您完成[服务申请](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=RunImageMediaTagging)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### URI URI格式 POST /v2/{project_id}/image/tagging 表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的区域需要和服务保持一致。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | language | 否 | String | **参数解释：** 语言类型。 **约束限制：** 不涉及。 **取值范围：** - zh：返回标签的语言类型为中文。 - en：返回标签的语言类型为英文。 **默认取值：** 默认值为zh。 | | threshold | 否 | Float | **参数解释：** 置信度的阈值。 **约束限制：** 不涉及。 **取值范围：** 取值范围是0-100。 **默认取值：** 默认值为60。 | | limit | 否 | Integer | **参数解释：** 最多返回的标签数。 **约束限制：** 不涉及。 **取值范围：** 最多150个，最少为1个。 **默认取值：** 不涉及。 | #### 响应参数 **状态码： 200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | result | [result] object | **参数解释：** 调用成功时为图像标签内容。 调用失败时无此字段。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5result | 参数 | 参数类型 | 描述 | |:---|:---|:---| | tags | Array of [ImageTaggingItemBody] objects | **参数解释：** 标签列表集合。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表6ImageTaggingItemBody | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | **参数解释：** 目标检测框信息，为空则表示没有目标检测框。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表7i18n_tag | 参数 | 参数类型 | 描述 | |:---|:---|:---| | zh | String | **参数解释：** 中文标签。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | en | String | **参数解释：** 英文标签。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表8i18n_type | 参数 | 参数类型 | 描述 | |:---|:---|:---| | zh | String | **参数解释：** 中文标签类别。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | en | String | **参数解释：** 英文标签类别。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表9ImageTaggingInstance | 参数 | 参数类型 | 描述 | |:---|:---|:---| | bounding_box | [BoundingBoxFloat] Object | **参数解释：** 目标检测框位置信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | confidence | String | **参数解释：** 检测标签置信度，将Float型置信度转为String类型返回，Float取值范围（0\~100）。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表10BoundingBoxFloat | 参数 | 参数类型 | 描述 | |:---|:---|:---| | width | Double | **参数解释：** 检测框区域宽度。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | height | Double | **参数解释：** 检测框区域高度。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | top_left_x | Double | **参数解释：** 检测框左上角到垂直轴距离。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | top_left_y | Double | **参数解释：** 检测框左上角到水平轴距离。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | **状态码： 400** 表11响应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/tagging"，"project_id"为项目ID，获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-image/image_03_0035.html)。 - 方式一：使用图片的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 | 失败响应结果。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。