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 |
支持的认知服务终结点。 |
description
|
query |
生成说明时关闭指定的域模型。 |
||
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”。 |
|
visual
|
query |
一个字符串,指示要返回的视觉特征类型。 多个值应以逗号分隔。 有效的视觉特征类型包括:类别 - 根据文档中定义的分类对图像内容进行分类。 标记 - 使用与图像内容相关的字词的详细列表标记图像。 说明 - 用完整的英语句子描述图像内容。 人脸 - 检测人脸是否存在。 如果存在,请生成坐标、性别和年龄。 ImageType - 检测图像是否为剪贴画或线条绘图。 颜色 - 确定主题色、主色以及图像是否为黑色&白色。 成人 - 检测图像是否是色情性质(描绘裸体或性行为),或是血腥(描绘极端暴力或血液)。 也检测到性暗示内容(即猥亵内容)。 对象 - 检测图像中的各种对象,包括近似位置。 Objects 参数仅在英语中可用。 品牌 - 检测图像中的各种品牌,包括近似位置。 “品牌”参数仅在英语中可用。 |
请求头
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
Ocp-Apim-Subscription-Key | True |
string |
请求正文
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
url | True |
string |
图像的可公开访问 URL。 |
响应
名称 | 类型 | 说明 |
---|---|---|
200 OK |
响应包含 JSON 格式的提取特征。 下面是枚举类型的定义: ClipartType 非 - 剪贴画 = 0,模棱两可 = 1,普通 - 剪贴画 = 2,良好 - 剪贴画 = 3。 LineDrawingTypeNon - LineDrawing = 0,LineDrawing = 1。 |
|
Other Status Codes |
错误响应。 |
安全性
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
}
}
]
}
定义
名称 | 说明 |
---|---|
Adult |
描述图像是否包含面向成人的内容和/或不雅的对象。 |
Bounding |
图像内区域的边界框。 |
Category |
描述已标识类别的对象。 |
Category |
描述其他类别详细信息的对象。 |
Celebrities |
描述可能的名人标识的对象。 |
Color |
提供描述颜色属性的其他元数据的对象。 |
Computer |
API 请求错误。 |
Computer |
错误代码。 |
Computer |
API 错误响应。 |
Computer |
有关 API 请求错误的详细信息。 |
Computer |
错误代码。 |
Description |
生成说明时关闭指定的域模型。 |
Details |
一个字符串,指示要返回的特定于域的详细信息。 多个值应以逗号分隔。 有效的视觉特征类型包括:名人 - 如果图像中检测到名人,则标识名人,地标 - 标识图像中的显著特征点。 |
Detected |
图像中检测到的品牌。 |
Detected |
在图像中检测到的对象。 |
Face |
描述图像中标识的人脸的对象。 |
Face |
描述人脸矩形的对象。 |
Gender |
人脸的可能性别。 |
Image |
AnalyzeImage作的结果。 |
Image |
图像标题,即图像描述的简要说明。 |
Image |
内容标记的集合,以及按置信度和图像元数据排序的标题列表。 |
Image |
图像元数据。 |
Image |
图像中的实体观察以及置信度分数。 |
Image |
提供可能的图像类型和匹配置信度的对象。 |
Image |
|
Landmarks |
图像中识别的地标。 |
Object |
在图像中检测到的对象。 |
Visual |
一个字符串,指示要返回的视觉特征类型。 多个值应以逗号分隔。 有效的视觉特征类型包括:类别 - 根据文档中定义的分类对图像内容进行分类。 标记 - 使用与图像内容相关的字词的详细列表标记图像。 说明 - 用完整的英语句子描述图像内容。 人脸 - 检测人脸是否存在。 如果存在,请生成坐标、性别和年龄。 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 |
标识类别的详细信息。 |
|
name |
string |
类别的名称。 |
score |
number (double) |
类别的评分。 |
CategoryDetail
描述其他类别详细信息的对象。
名称 | 类型 | 说明 |
---|---|---|
celebrities |
名人数组(如果有)。 |
|
landmarks |
标识的任何特征点的数组。 |
CelebritiesModel
描述可能的名人标识的对象。
名称 | 类型 | 说明 |
---|---|---|
confidence |
number (double) |
名人识别的置信度为 0 到 1 的值。 |
faceRectangle |
图像中标识的人脸的位置。 |
|
name |
string |
名人的名称。 |
ColorInfo
提供描述颜色属性的其他元数据的对象。
名称 | 类型 | 说明 |
---|---|---|
accentColor |
string |
可能的主题色。 |
dominantColorBackground |
string |
可能的主导背景色。 |
dominantColorForeground |
string |
可能的占主导地位的前景色。 |
dominantColors |
string[] |
可能的主要颜色的数组。 |
isBWImg |
boolean |
一个值,该值指示图像是否为黑白。 |
ComputerVisionError
API 请求错误。
名称 | 类型 | 说明 |
---|---|---|
code |
错误代码。 |
|
innererror |
内部错误包含更具体的信息。 |
|
message |
string |
说明服务报告的错误的消息。 |
ComputerVisionErrorCodes
错误代码。
值 | 说明 |
---|---|
InternalServerError | |
InvalidArgument | |
InvalidRequest | |
ServiceUnavailable |
ComputerVisionErrorResponse
API 错误响应。
名称 | 类型 | 说明 |
---|---|---|
error |
错误内容。 |
ComputerVisionInnerError
有关 API 请求错误的详细信息。
名称 | 类型 | 说明 |
---|---|---|
code |
错误代码。 |
|
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 |
检测到的品牌大致位置。 |
DetectedObject
在图像中检测到的对象。
名称 | 类型 | 说明 |
---|---|---|
confidence |
number (double) |
观察图像中对象的置信度分数,其值为 0 到 1。 |
object |
string |
对象的标签。 |
parent |
父对象,从分类的角度来看。 父对象是此对象的更通用形式。 例如,“斗牛犬”的父级为“狗”。 |
|
rectangle |
检测到对象的大致位置。 |
FaceDescription
描述图像中标识的人脸的对象。
名称 | 类型 | 说明 |
---|---|---|
age |
integer (int32) |
人脸的可能年龄。 |
faceRectangle |
包含已标识人脸的图像中的矩形。 |
|
gender |
人脸的可能性别。 |
FaceRectangle
描述人脸矩形的对象。
名称 | 类型 | 说明 |
---|---|---|
height |
integer (int32) |
从人脸左上角测量的高度(以像素为单位)。 |
left |
integer (int32) |
人脸左上角点的 X 坐标(以像素为单位)。 |
top |
integer (int32) |
人脸左上角点的 Y 坐标(以像素为单位)。 |
width |
integer (int32) |
从人脸左上角的宽度(以像素为单位)。 |
Gender
人脸的可能性别。
值 | 说明 |
---|---|
Female | |
Male |
ImageAnalysis
AnalyzeImage作的结果。
名称 | 类型 | 说明 |
---|---|---|
adult |
描述图像是否包含面向成人的内容和/或不雅的对象。 |
|
brands |
图像中检测到的品牌数组。 |
|
categories |
Category[] |
一个数组,指示标识的类别。 |
color |
提供描述颜色属性的其他元数据的对象。 |
|
description |
内容标记的集合,以及按置信度和图像元数据排序的标题列表。 |
|
faces |
图像中可能的人脸的数组。 |
|
imageType |
提供可能的图像类型和匹配置信度的对象。 |
|
metadata |
图像元数据。 |
|
modelVersion |
string pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$ |
AI 模型的版本。 |
objects |
描述图像中检测到的内容的对象数组。 |
|
requestId |
string |
REST API 请求的 ID。 |
tags |
Image |
具有置信度标记的列表。 |
ImageCaption
图像标题,即图像描述的简要说明。
名称 | 类型 | 说明 |
---|---|---|
confidence |
number (double) |
服务在标题中具有的置信度级别。 |
text |
string |
标题的文本。 |
ImageDescriptionDetails
内容标记的集合,以及按置信度和图像元数据排序的标题列表。
名称 | 类型 | 说明 |
---|---|---|
captions |
标题列表,按置信度排序。 |
|
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 |
父对象,从分类的角度来看。 父对象是此对象的更通用形式。 例如,“斗牛犬”的父级为“狗”。 |
VisualFeatureTypes
一个字符串,指示要返回的视觉特征类型。 多个值应以逗号分隔。 有效的视觉特征类型包括:类别 - 根据文档中定义的分类对图像内容进行分类。 标记 - 使用与图像内容相关的字词的详细列表标记图像。 说明 - 用完整的英语句子描述图像内容。 人脸 - 检测人脸是否存在。 如果存在,请生成坐标、性别和年龄。 ImageType - 检测图像是否为剪贴画或线条绘图。 颜色 - 确定主题色、主色以及图像是否为黑色&白色。 成人 - 检测图像是否是色情性质(描绘裸体或性行为),或是血腥(描绘极端暴力或血液)。 也检测到性暗示内容(即猥亵内容)。 对象 - 检测图像中的各种对象,包括近似位置。 Objects 参数仅在英语中可用。 品牌 - 检测图像中的各种品牌,包括近似位置。 “品牌”参数仅在英语中可用。
值 | 说明 |
---|---|
Adult | |
Brands | |
Categories | |
Color | |
Description | |
Faces | |
ImageType | |
Objects | |
Tags |