你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Analyze Image - Analyze Image

参考

Service:: Cognitive Services - Computer Vision

API Version:: 3.2

此操作根据图像内容提取一组丰富的可视特征。支持两种输入方法 -- (1) 上传图像; (2) 指定图像 URL。在请求中，有一个可选参数，用于选择要返回的功能。默认情况下，图像类别在响应中返回。成功响应将以 JSON 格式返回。如果请求失败，响应将包含错误代码和消息，以帮助了解问题所在。

POST {Endpoint}/vision/v3.2/analyze

With optional parameters:

POST {Endpoint}/vision/v3.2/analyze?visualFeatures={visualFeatures}&details={details}&language={language}&descriptionExclude={descriptionExclude}&model-version={model-version}

URI 参数

名称	在	必需	类型	说明
Endpoint	path	True	string	支持的认知服务终结点。
descriptionExclude	query		DescriptionExclude[]	生成说明时关闭指定的域模型。
details	query		Details[]	一个字符串，指示要返回哪些特定于域的详细信息。多个值应以逗号分隔。有效的视觉特征类型包括：名人 - 标识在图像中检测到的名人，陆标 - 标识图像中值得注意的地标。
language	query		string	输出生成所需的语言。如果未指定此属性，则默认值为“en”。有关支持的语言列表，请参阅 https://aka.ms/cv-languages 。
model-version	query		string	可选参数，用于指定 AI 模型的版本。接受的值为：“latest”、“2021-04-01”、“2021-05-01”。默认为“latest”。 Regex pattern: `^(latest\|\d{4}-\d{2}-\d{2})(-preview)?$`
visualFeatures	query		VisualFeatureTypes[]	一个字符串，指示要返回的视觉特征类型。多个值应以逗号分隔。有效的视觉特征类型包括：类别 - 根据文档中定义的分类对图像内容进行分类。标记 - 使用与图像内容相关的字词的详细列表标记图像。 Description - 用完整的英文句子描述图像内容。人脸 - 检测人脸是否存在。如果存在，则生成位置、性别和年龄。 ImageType - 检测图像是剪贴画还是素描。颜色 - 确定主题色、主导颜色以及图像是否为黑色&白色。成人 - 检测图像是否是色情性质 (描绘裸体或性行为) ，或血腥 (描绘极端暴力或血) 。还会检测性暗示内容（也称为不雅内容）。对象 - 检测图像中的各种对象，包括近似位置。 Objects 参数仅以英语提供。品牌 - 检测图像中的各种品牌，包括大致位置。品牌参数仅以英语提供。

请求头

名称	必需	类型	说明
Ocp-Apim-Subscription-Key	True	string

请求正文

名称	必需	类型	说明
url	True	string	图像的可公开访问 URL。

响应

名称	类型	说明
200 OK	ImageAnalysis	响应包含 JSON 格式的提取特征。下面是枚举类型的定义： ClipartType Non - clipart = 0，ambiguous = 1，normal - clipart = 2，good - clipart = 3。 LineDrawingTypeNon - LineDrawing = 0，LineDrawing = 1。
Other Status Codes	ComputerVisionErrorResponse	错误响应。

名称

类型

说明

200 OK

ImageAnalysis

响应包含 JSON 格式的提取特征。下面是枚举类型的定义：

ClipartType

Non - clipart = 0，ambiguous = 1，normal - clipart = 2，good - clipart = 3。 LineDrawingTypeNon - LineDrawing = 0，LineDrawing = 1。

Other Status Codes

ComputerVisionErrorResponse

错误响应。

安全性

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

示例

Successful AnalyzeImage request

Sample Request

HTTP

POST https://westus.api.cognitive.microsoft.com/vision/v3.2/analyze?visualFeatures=Categories,Adult,Tags,Description,Faces,Color,ImageType,Objects,Brands&details=Celebrities,Landmarks&language=en


{
  "url": "{url}"
}

Sample Response

Status code:: 200

{
  "categories": [
    {
      "name": "abstract_",
      "score": 0.00390625
    },
    {
      "name": "people_",
      "score": 0.83984375,
      "detail": {
        "celebrities": [
          {
            "name": "Satya Nadella",
            "faceRectangle": {
              "left": 597,
              "top": 162,
              "width": 248,
              "height": 248
            },
            "confidence": 0.999028444
          }
        ]
      }
    },
    {
      "name": "building_",
      "score": 0.984375,
      "detail": {
        "landmarks": [
          {
            "name": "Forbidden City",
            "confidence": 0.9829016923904419
          }
        ]
      }
    }
  ],
  "adult": {
    "isAdultContent": false,
    "isRacyContent": false,
    "isGoryContent": false,
    "adultScore": 0.0934349000453949,
    "racyScore": 0.06861349195241928,
    "goreScore": 0.012872257380997575
  },
  "tags": [
    {
      "name": "person",
      "confidence": 0.9897908568382263
    },
    {
      "name": "man",
      "confidence": 0.9449388980865479
    },
    {
      "name": "outdoor",
      "confidence": 0.938492476940155
    },
    {
      "name": "window",
      "confidence": 0.8951393961906433
    },
    {
      "name": "pangolin",
      "confidence": 0.7250059783791661,
      "hint": "mammal"
    }
  ],
  "description": {
    "tags": [
      "person",
      "man",
      "outdoor",
      "window",
      "glasses"
    ],
    "captions": [
      {
        "text": "Satya Nadella sitting on a bench",
        "confidence": 0.48293603002174407
      }
    ]
  },
  "requestId": "0dbec5ad-a3d3-4f7e-96b4-dfd57efe967d",
  "metadata": {
    "width": 1500,
    "height": 1000,
    "format": "Jpeg"
  },
  "modelVersion": "2021-04-01",
  "faces": [
    {
      "age": 44,
      "gender": "Male",
      "faceRectangle": {
        "left": 593,
        "top": 160,
        "width": 250,
        "height": 250
      }
    }
  ],
  "color": {
    "dominantColorForeground": "Brown",
    "dominantColorBackground": "Brown",
    "dominantColors": [
      "Brown",
      "Black"
    ],
    "accentColor": "873B59",
    "isBWImg": false
  },
  "imageType": {
    "clipArtType": 0,
    "lineDrawingType": 0
  },
  "objects": [
    {
      "rectangle": {
        "x": 0,
        "y": 0,
        "w": 50,
        "h": 50
      },
      "object": "tree",
      "confidence": 0.9,
      "parent": {
        "object": "plant",
        "confidence": 0.95
      }
    }
  ],
  "brands": [
    {
      "name": "Pepsi",
      "confidence": 0.857,
      "rectangle": {
        "x": 489,
        "y": 79,
        "w": 161,
        "h": 177
      }
    },
    {
      "name": "Coca-Cola",
      "confidence": 0.893,
      "rectangle": {
        "x": 216,
        "y": 55,
        "w": 171,
        "h": 372
      }
    }
  ]
}

定义

名称	说明
AdultInfo	描述图像是否包含面向成人的内容和/或是否不雅的对象。
BoundingRect	图像内部区域的边框。
Category	描述已标识类别的对象。
CategoryDetail	描述其他类别详细信息的对象。
CelebritiesModel	描述可能的名人标识的对象。
ColorInfo	一个对象，提供描述颜色属性的其他元数据。
ComputerVisionError	API 请求错误。
ComputerVisionErrorCodes	错误代码。
ComputerVisionErrorResponse	API 错误响应。
ComputerVisionInnerError	有关 API 请求错误的详细信息。
ComputerVisionInnerErrorCodeValue	错误代码。
DescriptionExclude	生成说明时关闭指定的域模型。
Details	一个字符串，指示要返回哪些特定于域的详细信息。多个值应以逗号分隔。有效的视觉特征类型包括：名人 - 标识名人（如果在图像中检测到），地标 - 标识图像中的显著地标。
DetectedBrand	在图像中检测到的品牌。
DetectedObject	在图像中检测到的对象。
FaceDescription	描述图像中标识的人脸的对象。
FaceRectangle	描述人脸矩形的对象。
Gender	人脸的可能性别。
ImageAnalysis	AnalyzeImage 操作的结果。
ImageCaption	图像描述文字，即图像描述的内容的简要说明。
ImageDescriptionDetails	内容标记的集合，以及按置信度级别排序的标题列表和图像元数据。
ImageMetadata	图像元数据。
ImageTag	图像中的实体观察值以及置信度分数。
ImageType	提供可能的图像类型和匹配的置信度级别的对象。
ImageUrl
LandmarksModel	在图像中识别的陆标。
ObjectHierarchy	在图像中检测到的对象。
VisualFeatureTypes	一个字符串，指示要返回的视觉特征类型。多个值应以逗号分隔。有效的视觉特征类型包括：类别 - 根据文档中定义的分类对图像内容进行分类。标记 - 使用与图像内容相关的字词的详细列表标记图像。 Description - 用完整的英文句子描述图像内容。人脸 - 检测人脸是否存在。如果存在，则生成位置、性别和年龄。 ImageType - 检测图像是剪贴画还是素描。颜色 - 确定主题色、主要颜色以及图像是否为黑色&白色。成人 - 检测图像是否是色情性质 (描绘裸体或性行为) ，或是血腥 (描绘极端暴力或血) 。还会检测性暗示内容（也称为不雅内容）。对象 - 检测图像中的各种对象，包括近似位置。 Objects 参数仅以英语提供。品牌 - 检测图像中的各种品牌，包括大致位置。品牌参数仅以英语提供。

AdultInfo

描述图像是否包含面向成人的内容和/或是否不雅的对象。

名称	类型	说明
adultScore	number	分数从 0 到 1，表示图像中被视为面向成人的内容。
goreScore	number	分数从 0 到 1，指示图像的 gory 如何。
isAdultContent	boolean	一个值，该值指示图像是否包含面向成人的内容。
isGoryContent	boolean	一个值，该值指示图像是否为 gory。
isRacyContent	boolean	一个值，该值指示图像是否不雅。
racyScore	number	分数从 0 到 1，表示图像的暗示性。

BoundingRect

图像内部区域的边框。

名称	类型	说明
h	integer	从区域左上角点测得的高度（以像素为单位）。
w	integer	从区域左上角点测得的宽度（以像素为单位）。
x	integer	区域的左上角点的 X 坐标（以像素为单位）。
y	integer	区域的左上角点的 Y 坐标（以像素为单位）。

名称	类型	说明
detail	CategoryDetail	标识的类别的详细信息。
name	string	类别的名称。
score	number	类别的评分。

CategoryDetail

描述其他类别详细信息的对象。

名称	类型	说明
celebrities	CelebritiesModel[]	名人数组（如果已识别）。
landmarks	LandmarksModel[]	一个标记数组（如果已识别）。

CelebritiesModel

描述可能的名人标识的对象。

名称	类型	说明
confidence	number	名人识别的置信度为值，范围为 0 到 1。
faceRectangle	FaceRectangle	图像中识别的人脸的位置。
name	string	名人的名称。

ColorInfo

一个对象，提供描述颜色属性的其他元数据。

名称	类型	说明
accentColor	string	可能的主题色。
dominantColorBackground	string	可能的主要背景色。
dominantColorForeground	string	可能的主导前景色。
dominantColors	string[]	可能的主要颜色的数组。
isBWImg	boolean	一个值，该值指示图像是黑白的。

ComputerVisionError

API 请求错误。

名称	类型	说明
code	ComputerVisionErrorCodes	错误代码。
innererror	ComputerVisionInnerError	内部错误包含更具体的信息。
message	string	解释服务报告的错误的消息。

ComputerVisionErrorCodes

错误代码。

名称	类型	说明
InternalServerError	string
InvalidArgument	string
InvalidRequest	string
ServiceUnavailable	string

ComputerVisionErrorResponse

API 错误响应。

名称	类型	说明
error	ComputerVisionError	错误内容。

ComputerVisionInnerError

有关 API 请求错误的详细信息。

名称	类型	说明
code	ComputerVisionInnerErrorCodeValue	错误代码。
message	string	错误消息。

ComputerVisionInnerErrorCodeValue

错误代码。

名称	类型	说明
BadArgument	string
CancelledRequest	string
DetectFaceError	string
FailedToProcess	string
InternalServerError	string
InvalidDetails	string
InvalidImageFormat	string
InvalidImageSize	string
InvalidImageUrl	string
InvalidModel	string
InvalidThumbnailSize	string
NotSupportedFeature	string
NotSupportedImage	string
NotSupportedLanguage	string
NotSupportedVisualFeature	string
StorageException	string
Timeout	string
Unspecified	string
UnsupportedMediaType	string

DescriptionExclude

生成说明时关闭指定的域模型。

名称	类型	说明
Celebrities	string
Landmarks	string

Details

一个字符串，指示要返回哪些特定于域的详细信息。多个值应以逗号分隔。有效的视觉特征类型包括：名人 - 标识名人（如果在图像中检测到），地标 - 标识图像中的显著地标。

名称	类型	说明
Celebrities	string
Landmarks	string

DetectedBrand

在图像中检测到的品牌。

名称	类型	说明
confidence	number	观察到图像中品牌的置信度分数，值为 0 到 1。
name	string	品牌的标签。
rectangle	BoundingRect	检测到的品牌的大致位置。

DetectedObject

在图像中检测到的对象。

名称	类型	说明
confidence	number	观察到图像中对象的置信度分数，值为 0 到 1。
object	string	对象的标签。
parent	ObjectHierarchy	从分类的角度来看，父对象。父对象是此对象的一种更通用的形式。例如，“斗牛犬”的父母是“狗”。
rectangle	BoundingRect	检测到的对象的大致位置。

FaceDescription

描述图像中标识的人脸的对象。

名称	类型	说明
age	integer	人脸的可能年龄。
faceRectangle	FaceRectangle	包含已识别人脸的图像中的矩形。
gender	Gender	人脸的可能性别。

FaceRectangle

描述人脸矩形的对象。

名称	类型	说明
height	integer	高度从人脸的左上角点测量，以像素为单位。
left	integer	人脸左上角点的 X 坐标（以像素为单位）。
top	integer	人脸左上角点的 Y 坐标（以像素为单位）。
width	integer	从人脸的左上角点测量的宽度（以像素为单位）。

Gender

人脸的可能性别。

名称	类型	说明
Female	string
Male	string

ImageAnalysis

AnalyzeImage 操作的结果。

名称	类型	说明
adult	AdultInfo	描述图像是否包含面向成人的内容和/或是否不雅的对象。
brands	DetectedBrand[]	在图像中检测到的品牌数组。
categories	Category[]	一个数组，指示已标识的类别。
color	ColorInfo	一个对象，提供描述颜色属性的其他元数据。
description	ImageDescriptionDetails	内容标记的集合，以及按置信度级别排序的标题列表和图像元数据。
faces	FaceDescription[]	图像中可能的人脸的数组。
imageType	ImageType	提供可能的图像类型和匹配的置信度级别的对象。
metadata	ImageMetadata	图像元数据。
modelVersion	string	AI 模型的版本。
objects	DetectedObject[]	描述图像中检测到的内容的对象数组。
requestId	string	REST API 请求的 ID。
tags	ImageTag[]	具有置信度级别的标记列表。

ImageCaption

图像描述文字，即图像描述的内容的简要说明。

名称	类型	说明
confidence	number	服务对描述文字的置信度级别。
text	string	描述文字的文本。

ImageDescriptionDetails

内容标记的集合，以及按置信度级别排序的标题列表和图像元数据。

名称	类型	说明
captions	ImageCaption[]	标题列表，按置信度排序。
tags	string[]	图像标记的集合。

ImageMetadata

图像元数据。

名称	类型	说明
format	string	图像格式。
height	integer	图像高度（以像素为单位）。
width	integer	图像宽度（以像素为单位）。

ImageTag

图像中的实体观察值以及置信度分数。

名称	类型	说明
confidence	number	观察到实体的置信度。
hint	string	此标记的可选提示/详细信息。
name	string	实体的名称。

ImageType

提供可能的图像类型和匹配的置信度级别的对象。

名称	类型	说明
clipArtType	integer	图像是剪贴画的置信度。
lineDrawingType	integer	图像是线条绘制的置信度。

ImageUrl

名称	类型	说明
url	string	图像的可公开访问 URL。

LandmarksModel

在图像中识别的陆标。

名称	类型	说明
confidence	number	特征点识别值的置信度级别，范围为 0 到 1。
name	string	陆标的名称。

ObjectHierarchy

在图像中检测到的对象。

名称	类型	说明
confidence	number	观察到图像中对象的置信度分数，其值为 0 到 1。
object	string	对象的标签。
parent	ObjectHierarchy	父对象，从分类的角度来看。父对象是此对象的更通用形式。例如，“斗牛犬”的父级为“dog”。

VisualFeatureTypes

一个字符串，指示要返回的视觉特征类型。多个值应以逗号分隔。有效的视觉特征类型包括：类别 - 根据文档中定义的分类对图像内容进行分类。标记 - 使用与图像内容相关的字词的详细列表标记图像。 Description - 用完整的英文句子描述图像内容。人脸 - 检测人脸是否存在。如果存在，则生成位置、性别和年龄。 ImageType - 检测图像是剪贴画还是素描。颜色 - 确定主题色、主要颜色以及图像是否为黑色&白色。成人 - 检测图像是否是色情性质 (描绘裸体或性行为) ，或是血腥 (描绘极端暴力或血) 。还会检测性暗示内容（也称为不雅内容）。对象 - 检测图像中的各种对象，包括近似位置。 Objects 参数仅以英语提供。品牌 - 检测图像中的各种品牌，包括大致位置。品牌参数仅以英语提供。

名称	类型	说明
Adult	string
Brands	string
Categories	string
Color	string
Description	string
Faces	string
ImageType	string
Objects	string
Tags	string

通过

Analyze Image - Analyze Image

URI 参数

请求头

请求正文

响应

安全性

Ocp-Apim-Subscription-Key

示例

Successful AnalyzeImage request

Sample Request

Sample Response

定义

AdultInfo

BoundingRect

Category

CategoryDetail

CelebritiesModel

ColorInfo

ComputerVisionError

ComputerVisionErrorCodes

ComputerVisionErrorResponse

ComputerVisionInnerError

ComputerVisionInnerErrorCodeValue

DescriptionExclude

Details

DetectedBrand

DetectedObject

FaceDescription

FaceRectangle

Gender

ImageAnalysis

ImageCaption

ImageDescriptionDetails

ImageMetadata

ImageTag

ImageType

ImageUrl

LandmarksModel

ObjectHierarchy

VisualFeatureTypes

其他资源