调用图像分析 3.2 API

本文演示如何调用图像分析 3.2 API 以返回有关图像的视觉特征的信息。 它还演示如何使用客户端 SDK 或 REST API 分析返回的信息。

本指南假设已经创建视觉资源并获得了密钥和终结点 URL。 如果使用客户端 SDK,则还需要对客户端对象进行身份验证。 如果尚未执行这些步骤,请按照快速入门开始操作。

提交服务数据

本指南中的代码使用 URL 引用的远程图像。 你可能要自行尝试不同的图像,以了解图像分析功能的完整功能。

分析远程图像时,请通过设置请求正文的格式来指定图像的 URL,如下所示:{"url":"http://example.com/images/test.jpg"}

若要分析本地图像,请将二进制图像数据放在 HTTP 请求正文中。

确定如何处理数据

选择视觉特征

使用分析 API 可以访问所有服务的图像分析特征。 基于自己的用例选择要执行的操作。 有关每种特征的说明,请参阅概述。 以下章节中的示例添加了所有可用的视觉特征,但对于实际使用,可能只需要一两种特征。

可以通过设置分析 API 的 URL 查询参数来指定要使用的特征。 参数可以具有多个值(用逗号分隔)。 指定的每项特征都需要更多计算时间,因此只需指定所需的特征。

URL 参数 说明
features Read 读取图像中的可见文本并将其输出为结构化 JSON 数据。
features Description 用受支持的语言以完整的句子描述图像内容。
features SmartCrops 查找将图像裁剪为所需纵横比的矩形坐标,同时保留感兴趣的区域。
features Objects 检测图像中的各种对象,包括大致位置。 Objects 参数仅以英语提供。
features Tags 使用与图像内容相关字词的详细列表来标记图像。

填充的 URL 可能如下所示:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags

指定语言

还可以指定返回的数据的语言。

以下 URL 查询参数指定语言。 默认值为 en

URL 参数 说明
language en 英语
language es 西班牙语
language ja 日语
language pt 葡萄牙语
language zh 简体中文

填充的 URL 可能如下所示:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags&language=en

获取服务结果

本部分演示如何分析 API 调用的结果。 它包括 API 调用本身。

注意

范围内 API 调用

可以直接调用图像分析中的某些特征,也可以通过分析 API 调用来调用。 例如,可以通过向 <endpoint>/vision/v3.2/tag(或是向 SDK 中的对应方法)发出请求,来执行仅限图像标记的作用域分析。 有关可单独调用的其他特征,请参阅参考文档

服务返回 200 HTTP 响应,正文包含 JSON 字符串形式的返回数据。 以下文本是一个 JSON 响应示例。

{
    "metadata":
    {
        "width": 300,
        "height": 200
    },
    "tagsResult":
    {
        "values":
        [
            {
                "name": "grass",
                "confidence": 0.9960499405860901
            },
            {
                "name": "outdoor",
                "confidence": 0.9956876635551453
            },
            {
                "name": "building",
                "confidence": 0.9893627166748047
            },
            {
                "name": "property",
                "confidence": 0.9853052496910095
            },
            {
                "name": "plant",
                "confidence": 0.9791355729103088
            }
        ]
    }
}

错误代码

请参阅以下可能出现的错误及其原因的列表:

  • 400
    • InvalidImageUrl - 图片 URL 格式不正确或无法访问。
    • InvalidImageFormat - 输入数据不是有效的图像。
    • InvalidImageSize - 输入的图像太大。
    • NotSupportedVisualFeature - 指定的特征类型无效。
    • NotSupportedImage - 不受支持的图片,例如儿童色情内容。
    • InvalidDetails - 不支持的 detail 参数值。
    • NotSupportedLanguage - 指定的语言不支持请求的操作。
    • BadArgument - 错误消息中提供了更多详细信息。
  • 415 - 不支持的媒体类型。 Content-Type 类型不在允许的类型中:
    • 对于图像 URL,Content-Type 应为 application/json
    • 对于二进制图像数据,Content-Type 应为 application/octet-streammultipart/form-data
  • 500
    • FailedToProcess
    • Timeout - 图像处理超时。
    • InternalServerError

提示

使用 Azure AI 视觉时,可能会遇到服务强制实施的速率限制所导致的暂时性错误,或者网络中断等其他暂时性问题。 有关如何处理此类故障的信息,请参阅云设计模式指南中的重试模式,以及相关的断路器模式

后续步骤

  • 请浏览概念文章,了解有关每种特征的详细信息。