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

Analyze Image - Analyze Image

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

POST {Endpoint}/vision/v3.2/analyze
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

pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$

用于指定 AI 模型的版本的可选参数。 接受的值为:“latest”、“2021-04-01”、“2021-05-01”。 默认值为“latest”。

visualFeatures
query

VisualFeatureTypes[]

一个字符串,指示要返回的视觉特征类型。 多个值应以逗号分隔。 有效的视觉特征类型包括:类别 - 根据文档中定义的分类对图像内容进行分类。 标记 - 使用与图像内容相关的字词的详细列表标记图像。 说明 - 用完整的英语句子描述图像内容。 人脸 - 检测人脸是否存在。 如果存在,请生成坐标、性别和年龄。 ImageType - 检测图像是否为剪贴画或线条绘图。 颜色 - 确定主题色、主色以及图像是否为黑色&白色。 成人 - 检测图像是否是色情性质(描绘裸体或性行为),或是血腥(描绘极端暴力或血液)。 也检测到性暗示内容(即猥亵内容)。 对象 - 检测图像中的各种对象,包括近似位置。 Objects 参数仅在英语中可用。 品牌 - 检测图像中的各种品牌,包括近似位置。 “品牌”参数仅在英语中可用。

请求头

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

string

请求正文

名称 必需 类型 说明
url True

string

图像的可公开访问 URL。

响应

名称 类型 说明
200 OK

ImageAnalysis

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

ClipartType

非 - 剪贴画 = 0,模棱两可 = 1,普通 - 剪贴画 = 2,良好 - 剪贴画 = 3。 LineDrawingTypeNon - LineDrawing = 0,LineDrawing = 1。

Other Status Codes

ComputerVisionErrorResponse

错误响应。

安全性

Ocp-Apim-Subscription-Key

类型: apiKey
在: header

示例

Successful AnalyzeImage request

示例请求

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}"
}

示例响应

{
  "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

一个字符串,指示要返回的视觉特征类型。 多个值应以逗号分隔。 有效的视觉特征类型包括:类别 - 根据文档中定义的分类对图像内容进行分类。 标记 - 使用与图像内容相关的字词的详细列表标记图像。 说明 - 用完整的英语句子描述图像内容。 人脸 - 检测人脸是否存在。 如果存在,请生成坐标、性别和年龄。 ImageType - 检测图像是否为剪贴画或线条绘图。 颜色 - 确定主题色、主色以及图像是否为黑色&白色。 成人 - 检测图像是否是色情性质(描绘裸体或性行为),或是血腥(描绘极端暴力或血液)。 也检测到性暗示内容(即猥亵内容)。 对象 - 检测图像中的各种对象,包括近似位置。 Objects 参数仅在英语中可用。 品牌 - 检测图像中的各种品牌,包括近似位置。 “品牌”参数仅在英语中可用。

AdultInfo

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

名称 类型 说明
adultScore

number (double)

分数从 0 到 1,指示内容在图像中被视为面向成人的内容。

goreScore

number (double)

从 0 到 1 评分,指示古里图像的显示方式。

isAdultContent

boolean

一个值,该值指示图像是否包含面向成人的内容。

isGoryContent

boolean

一个值,该值指示图像是否为 gory。

isRacyContent

boolean

一个值,该值指示图像是否不雅。

racyScore

number (double)

评分从 0 到 1,指示图像的暗示性。

BoundingRect

图像内区域的边界框。

名称 类型 说明
h

integer (int32)

从区域左上角(以像素为单位)测量的高度。

w

integer (int32)

从区域的左上角点(以像素为单位)测量的宽度。

x

integer (int32)

区域的左上角点的 X 坐标(以像素为单位)。

y

integer (int32)

区域的左上角点的 Y 坐标(以像素为单位)。

Category

描述已标识类别的对象。

名称 类型 说明
detail

CategoryDetail

标识类别的详细信息。

name

string

类别的名称。

score

number (double)

类别的评分。

CategoryDetail

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

名称 类型 说明
celebrities

CelebritiesModel[]

名人数组(如果有)。

landmarks

LandmarksModel[]

标识的任何特征点的数组。

CelebritiesModel

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

名称 类型 说明
confidence

number (double)

名人识别的置信度为 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
InvalidArgument
InvalidRequest
ServiceUnavailable

ComputerVisionErrorResponse

API 错误响应。

名称 类型 说明
error

ComputerVisionError

错误内容。

ComputerVisionInnerError

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

名称 类型 说明
code

ComputerVisionInnerErrorCodeValue

错误代码。

message

string

错误信息。

ComputerVisionInnerErrorCodeValue

错误代码。

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

DescriptionExclude

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

说明
Celebrities
Landmarks

Details

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

说明
Celebrities
Landmarks

DetectedBrand

图像中检测到的品牌。

名称 类型 说明
confidence

number (double)

图像中观察到品牌的信心分数,其值为 0 到 1。

name

string

品牌标签。

rectangle

BoundingRect

检测到的品牌大致位置。

DetectedObject

在图像中检测到的对象。

名称 类型 说明
confidence

number (double)

观察图像中对象的置信度分数,其值为 0 到 1。

object

string

对象的标签。

parent

ObjectHierarchy

父对象,从分类的角度来看。 父对象是此对象的更通用形式。 例如,“斗牛犬”的父级为“狗”。

rectangle

BoundingRect

检测到对象的大致位置。

FaceDescription

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

名称 类型 说明
age

integer (int32)

人脸的可能年龄。

faceRectangle

FaceRectangle

包含已标识人脸的图像中的矩形。

gender

Gender

人脸的可能性别。

FaceRectangle

描述人脸矩形的对象。

名称 类型 说明
height

integer (int32)

从人脸左上角测量的高度(以像素为单位)。

left

integer (int32)

人脸左上角点的 X 坐标(以像素为单位)。

top

integer (int32)

人脸左上角点的 Y 坐标(以像素为单位)。

width

integer (int32)

从人脸左上角的宽度(以像素为单位)。

Gender

人脸的可能性别。

说明
Female
Male

ImageAnalysis

AnalyzeImage作的结果。

名称 类型 说明
adult

AdultInfo

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

brands

DetectedBrand[]

图像中检测到的品牌数组。

categories

Category[]

一个数组,指示标识的类别。

color

ColorInfo

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

description

ImageDescriptionDetails

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

faces

FaceDescription[]

图像中可能的人脸的数组。

imageType

ImageType

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

metadata

ImageMetadata

图像元数据。

modelVersion

string

pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$

AI 模型的版本。

objects

DetectedObject[]

描述图像中检测到的内容的对象数组。

requestId

string

REST API 请求的 ID。

tags

ImageTag[]

具有置信度标记的列表。

ImageCaption

图像标题,即图像描述的简要说明。

名称 类型 说明
confidence

number (double)

服务在标题中具有的置信度级别。

text

string

标题的文本。

ImageDescriptionDetails

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

名称 类型 说明
captions

ImageCaption[]

标题列表,按置信度排序。

tags

string[]

图像标记的集合。

ImageMetadata

图像元数据。

名称 类型 说明
format

string

图像格式。

height

integer (int32)

图像高度(以像素为单位)。

width

integer (int32)

图像宽度(以像素为单位)。

ImageTag

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

名称 类型 说明
confidence

number (double)

观察到实体的置信度级别。

hint

string

此标记的可选提示/详细信息。

name

string

实体的名称。

ImageType

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

名称 类型 说明
clipArtType

integer (int32)

图像是剪贴画的置信度。

lineDrawingType

integer (int32)

图像是线条绘制的置信度。

ImageUrl

名称 类型 说明
url

string

图像的可公开访问 URL。

LandmarksModel

图像中识别的地标。

名称 类型 说明
confidence

number (double)

特征点识别的置信度,其值为 0 到 1。

name

string

地标的名称。

ObjectHierarchy

在图像中检测到的对象。

名称 类型 说明
confidence

number (double)

观察图像中对象的置信度分数,其值为 0 到 1。

object

string

对象的标签。

parent

ObjectHierarchy

父对象,从分类的角度来看。 父对象是此对象的更通用形式。 例如,“斗牛犬”的父级为“狗”。

VisualFeatureTypes

一个字符串,指示要返回的视觉特征类型。 多个值应以逗号分隔。 有效的视觉特征类型包括:类别 - 根据文档中定义的分类对图像内容进行分类。 标记 - 使用与图像内容相关的字词的详细列表标记图像。 说明 - 用完整的英语句子描述图像内容。 人脸 - 检测人脸是否存在。 如果存在,请生成坐标、性别和年龄。 ImageType - 检测图像是否为剪贴画或线条绘图。 颜色 - 确定主题色、主色以及图像是否为黑色&白色。 成人 - 检测图像是否是色情性质(描绘裸体或性行为),或是血腥(描绘极端暴力或血液)。 也检测到性暗示内容(即猥亵内容)。 对象 - 检测图像中的各种对象,包括近似位置。 Objects 参数仅在英语中可用。 品牌 - 检测图像中的各种品牌,包括近似位置。 “品牌”参数仅在英语中可用。

说明
Adult
Brands
Categories
Color
Description
Faces
ImageType
Objects
Tags