# 标签识别-RunImageMediaTagging #### 功能介绍 对用户传入的图像可以返回图像中的物体名称、所属类别及置信度信息。 #### 前提条件 - 使用标签识别服务之前需要您完成[服务申请](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 POST /v2/{project_id}/image/media-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\]。 **默认取值：** 默认值为40。 | | limit | 否 | Integer | **参数解释：** 最多返回的标签数。 **约束限制：** 不涉及。 **取值范围：** 最多150个，最少为1个。 **默认取值：** 默认值为10。 | #### 响应参数 **状态码： 200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | result | [result] Object | **参数解释：** 调用成功时为图像标签内容。 调用失败时无此字段。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5result | 参数 | 参数类型 | 描述 | |:---|:---|:---| | tags | Array of [ImageMediaTaggingItemBody] Objects | **参数解释：** 标签列表集合。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表6ImageMediaTaggingItemBody | 参数 | 参数类型 | 描述 | |:---|:---|:---| | confidence | String | **参数解释：** 置信度，将Float型置信度转为String类型返回。 **约束限制：** 不涉及。 **取值范围：** 0-100。 **默认取值：** 不涉及。 | | type | String | **参数解释：** 标签的类别。返回的标签类型，包含二十多种大类，具体可以参考[图像标签分类](http://support.huaweicloud.com/image_faq/image_01_0037.html)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | tag | String | **参数解释：** 标签名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | i18n_tag | [i18n_tag] Object | **参数解释：** 标签的多种语言输出。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | i18n_type | [i18n_type] Object | **参数解释：** 标签类别的多种语言输出。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | instances | Array of [ImageMediaTaggingInstance] Objects | **参数解释：** 目标检测框信息，该字段为空（为兼容图像标签V2版本保留该字段，可忽略）。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表7i18n_tag | 参数 | 参数类型 | 描述 | |:---|:---|:---| | zh | String | **参数解释：** 中文标签。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | en | String | **参数解释：** 英文标签。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表8i18n_type | 参数 | 参数类型 | 描述 | |:---|:---|:---| | zh | String | **参数解释：** 中文标签类别。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | en | String | **参数解释：** 英文标签类别。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表9ImageMediaTaggingInstance | 参数 | 参数类型 | 描述 | |:---|:---|:---| | bounding_box | [BoundingBox] Object | **参数解释：** 目标检测框位置信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | confidence | String | **参数解释：** 检测标签置信度，将Float型置信度转为String类型返回，Float取值范围（0\~100）。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表10BoundingBox | 参数 | 参数类型 | 描述 | |:---|:---|:---| | width | Integer | **参数解释：** 检测框区域宽度。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | height | Integer | **参数解释：** 检测框区域高度。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | top_left_x | Integer | **参数解释：** 检测框左上角到垂直轴距离。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | top_left_y | Integer | **参数解释：** 检测框左上角到水平轴距离。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | **状态码： 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/media-tagging"，"project_id"为项目ID，获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-image/image_03_0035.html)。 - 方式一：使用图片的BASE64编码，对于用户传入的图像返回图像中的物体名称、所属类别及置信度信息，返回标签的语言类型为中文，最多返回的标签数为5。 ``` POST https://{endpoint}/v2/{project_id}/image/media-tagging { "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA...", "url" : "", "language" : "zh", "limit" : 5, "threshold" : 20 } ``` - 方式二：使用图片URL，对于用户传入的图像返回图像中的物体名称、所属类别及置信度信息，返回标签的语言类型为中文，最多返回的标签数为5。 ``` POST https://{endpoint}/v2/{project_id}/image/media-tagging { "image" : "", "url" : "https://support.huaweicloud.com/productdesc-image/zh-cn_image_0000001382844041.jpg", //此处更改为您需要识别的图片URL "language" : "zh", "limit" : 5, "threshold" : 20 } ``` #### 响应示例 **状态码： 200** 成功响应结果 ``` { "result": { "tags": [ { "confidence": "39.42", "i18n_tag": { "en": "Picnic", "zh": "野餐" }, "i18n_type": { "en": "Food", "zh": "食物" }, "instances": [], "tag": "野餐", "type": "食物" }, { "confidence": "30.19", "i18n_tag": { "en": "Miniature projector", "zh": "微型投影仪" }, "i18n_type": { "en": "Electronics", "zh": "电子类" }, "instances": [], "tag": "微型投影仪", "type": "电子类" }, { "confidence": "24.93", "i18n_tag": { "en": "Picnic Basket", "zh": "野餐篮" }, "i18n_type": { "en": "Home category", "zh": "家居类" }, "instances": [], "tag": "野餐篮", "type": "家居类" }, { "confidence": "21.58", "i18n_tag": { "en": "Harmonica", "zh": "口琴" }, "i18n_type": { "en": "Culture and art", "zh": "文化艺术类" }, "instances": [], "tag": "口琴", "type": "文化艺术类" } ] } } ``` **状态码： 400** 失败响应结果 ``` { "error_code" : "AIS.0005", "error_msg" : "The service does not exist." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 成功响应结果。 | | 400 | 失败响应结果。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。