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

Face Detection Operations - Detect From Url

参考

服务:: Azure AI Services

API 版本:: v1.2-preview.1

检测图像中的人脸、返回人脸矩形，还可以选择使用 faceIds、地标和属性。

重要

Microsoft已停用或有限的面部识别功能，可用于推断情绪状态和身份属性，如果滥用，可能会使人们受到陈规定型、歧视或不公平拒绝服务。退休的功能是情感和性别。有限的功能是年龄、微笑、面部毛发、头发和化妆。如果你有一个负责任的用例，可以从使用任何有限的功能中受益，请向 Azure 人脸 API 发送电子邮件 azureface@microsoft.com。 https://azure.microsoft.com/blog/responsible-ai-investments-and-safeguards-for-facial-recognition/阅读有关此决定的详细信息。

- 不会存储任何图像。仅提取的人脸功能存储在服务器上。 faceId 是人脸功能的标识符，将在“标识”、“验证”和“查找相似”中使用。存储的人脸功能将在原始检测调用后由 faceIdTimeToLive 指定的时间过期并被删除。
- 可选参数包括 faceId、地标和属性。属性包括 headPose、眼镜、遮挡、配件、模糊、曝光、噪音、掩码和质量ForRecognition。为特定属性返回的某些结果可能不太准确。
- 支持 JPEG、PNG、GIF（第一帧）和 BMP 格式。允许的图像文件大小从 1KB 到 6MB。
- 最小可检测人脸大小在图像中不超过 1920x1080 像素的 36x36 像素。尺寸高于 1920x1080 像素的图像将需要比例更大的最小人脸大小。
- 最多可以返回 100 张人脸作为图像。人脸按从大到小的人脸矩形大小进行排名。
- 若要获得最佳结果，请在查询“识别”、“验证”和“查找相似”（'returnFaceId'为 true）时，请使用正面、清晰且最小大小为 200x200 像素（眼睛之间的 100 像素）的人脸。
- 可以提供不同的“detectionModel”值。若要使用和比较不同的检测模型，请参阅 https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
  - “detection_02”：如果选择此检测模型，将禁用人脸属性和地标。
  - “detection_03”：如果选择此检测模型，则支持人脸属性（掩码、模糊和 headPose）和地标。
- 提供了不同的“recognitionModel”值。如果需要后续操作（如“Verify”、“Identify”、“Find Similar”），请使用“recognitionModel”参数指定识别模型。 “recognitionModel”的默认值为“recognition_01”，如果需要最新的模型，请显式指定此参数中所需的模型。指定后，检测到的 faceId 将与指定的识别模型相关联。有关详细信息，请参阅 https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-recognition-model。

POST {endpoint}/face/{apiVersion}/detect

具有可选参数:

POST {endpoint}/face/{apiVersion}/detect?detectionModel={detectionModel}&recognitionModel={recognitionModel}&returnFaceId={returnFaceId}&returnFaceAttributes={returnFaceAttributes}&returnFaceLandmarks={returnFaceLandmarks}&returnRecognitionModel={returnRecognitionModel}&faceIdTimeToLive={faceIdTimeToLive}

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的认知服务终结点（协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com）。
detectionModel	query		DetectionModel	与检测到的 faceId 关联的“detectionModel”。支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。默认值为“detection_01”。
faceIdTimeToLive	query		integer int32	正在缓存的人脸 ID 的秒数。支持的范围从 60 秒到 86400 秒。默认值为 86400 （24 小时）。
recognitionModel	query		RecognitionModel	与检测到的 faceId 关联的“recognitionModel”。支持的“recognitionModel”值包括“recognition_01”、“recognition_02”、“recognition_03”或“recognition_04”。默认值为“recognition_01”。建议使用“recognition_04”，因为与“recognition_03”相比，其面部戴面具的准确性得到改善，并且与“recognition_01”和“recognition_02”相比，其整体准确性得到改善。
returnFaceAttributes	query		FaceAttributeType[]	分析和返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=headPose，眼镜”。人脸属性分析具有额外的计算和时间成本。
returnFaceId	query		boolean	返回检测到的人脸的 faceId。默认值为 true。
returnFaceLandmarks	query		boolean	返回检测到的人脸的面部特征点。默认值为 false。
returnRecognitionModel	query		boolean	返回“recognitionModel”或“not”。默认值为 false。仅当 returnFaceId = true 时，这才适用。

请求正文

名称	必需	类型	说明
url	True	string	输入图像的 URL。

响应

名称	类型	说明
200 OK	FaceDetectionResult[]	成功的调用以降序返回按人脸矩形大小排名的人脸条目数组。空响应指示未检测到人脸。
Other Status Codes	FaceErrorResponse	意外的错误响应。标头 x-ms-error-code: string

名称

类型

说明

200 OK

FaceDetectionResult[]

成功的调用以降序返回按人脸矩形大小排名的人脸条目数组。空响应指示未检测到人脸。

Other Status Codes

FaceErrorResponse

意外的错误响应。

标头

x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 人脸订阅的密钥。

类型: apiKey
在: header

AADToken

Azure Active Directory OAuth2 流

类型: oauth2
流向: accessCode
授权 URL: https://api.example.com/oauth2/authorize
令牌 URL: https://api.example.com/oauth2/token

作用域

名称	说明
https://cognitiveservices.azure.com/.default

示例

Detect with Image URL

示例请求

HTTP

POST {endpoint}/face/v1.2-preview.1/detect?detectionModel=detection_01&recognitionModel=recognition_03&returnFaceId=True&returnFaceAttributes=glasses,headPose,occlusion,accessories,blur,exposure,noise,qualityForRecognition&returnFaceLandmarks=True&returnRecognitionModel=True&faceIdTimeToLive=60

{
  "url": "https://microsoft.com/example.jpg"
}

示例响应

状态代码:: 200

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "recognitionModel": "recognition_03",
    "faceRectangle": {
      "width": 78,
      "height": 78,
      "left": 394,
      "top": 54
    },
    "faceLandmarks": {
      "pupilLeft": {
        "x": 412.7,
        "y": 78.4
      },
      "pupilRight": {
        "x": 446.8,
        "y": 74.2
      },
      "noseTip": {
        "x": 437.7,
        "y": 92.4
      },
      "mouthLeft": {
        "x": 417.8,
        "y": 114.4
      },
      "mouthRight": {
        "x": 451.3,
        "y": 109.3
      },
      "eyebrowLeftOuter": {
        "x": 397.9,
        "y": 78.5
      },
      "eyebrowLeftInner": {
        "x": 425.4,
        "y": 70.5
      },
      "eyeLeftOuter": {
        "x": 406.7,
        "y": 80.6
      },
      "eyeLeftTop": {
        "x": 412.2,
        "y": 76.2
      },
      "eyeLeftBottom": {
        "x": 413,
        "y": 80.1
      },
      "eyeLeftInner": {
        "x": 418.9,
        "y": 78
      },
      "eyebrowRightInner": {
        "x": 4.8,
        "y": 69.7
      },
      "eyebrowRightOuter": {
        "x": 5.5,
        "y": 68.5
      },
      "eyeRightInner": {
        "x": 441.5,
        "y": 75
      },
      "eyeRightTop": {
        "x": 446.4,
        "y": 71.7
      },
      "eyeRightBottom": {
        "x": 447,
        "y": 75.3
      },
      "eyeRightOuter": {
        "x": 451.7,
        "y": 73.4
      },
      "noseRootLeft": {
        "x": 428,
        "y": 77.1
      },
      "noseRootRight": {
        "x": 435.8,
        "y": 75.6
      },
      "noseLeftAlarTop": {
        "x": 428.3,
        "y": 89.7
      },
      "noseRightAlarTop": {
        "x": 442.2,
        "y": 87
      },
      "noseLeftAlarOutTip": {
        "x": 424.3,
        "y": 96.4
      },
      "noseRightAlarOutTip": {
        "x": 446.6,
        "y": 92.5
      },
      "upperLipTop": {
        "x": 437.6,
        "y": 105.9
      },
      "upperLipBottom": {
        "x": 437.6,
        "y": 108.2
      },
      "underLipTop": {
        "x": 436.8,
        "y": 111.4
      },
      "underLipBottom": {
        "x": 437.3,
        "y": 114.5
      }
    },
    "faceAttributes": {
      "glasses": "sunglasses",
      "headPose": {
        "roll": 2.1,
        "yaw": 3,
        "pitch": 1.6
      },
      "occlusion": {
        "foreheadOccluded": false,
        "eyeOccluded": false,
        "mouthOccluded": false
      },
      "accessories": [
        {
          "type": "headwear",
          "confidence": 0.99
        },
        {
          "type": "glasses",
          "confidence": 1
        },
        {
          "type": "mask",
          "confidence": 0.87
        }
      ],
      "blur": {
        "blurLevel": "medium",
        "value": 0.51
      },
      "exposure": {
        "exposureLevel": "goodExposure",
        "value": 0.55
      },
      "noise": {
        "noiseLevel": "low",
        "value": 0.12
      },
      "qualityForRecognition": "high"
    }
  }
]

定义

名称	说明
AccessoryItem	附件项和相应的置信度。
AccessoryType	附件的类型。
BlurLevel	指示模糊程度。
BlurProperties	描述图像中存在模糊状态的属性。
DetectionModel	与检测到的 faceId 关联的“detectionModel”。支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。默认值为“detection_01”。
ExposureLevel	指示曝光级别。
ExposureProperties	描述图像曝光级别的属性。
FaceAttributes	检测到的人脸的人脸属性。
FaceAttributeType	分析和返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=headPose，眼镜”。人脸属性分析具有额外的计算和时间成本。
FaceDetectionResult	检测 API 的响应。
FaceError	错误对象。有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。
FaceLandmarks	27 磅人脸特征点的集合，指向人脸组件的重要位置。
FaceRectangle	在其中可以找到人脸的矩形。
FacialHair	描述面部头发属性的属性。
GlassesType	眼镜类型的人脸。
HairColor	候选颜色和置信度数组，存在于每个颜色和置信度中。
HairColorType	头发颜色的名称。
HairProperties	描述头发属性的属性。
HeadPose	3D 滚/偏航/俯仰角度用于人脸方向。
LandmarkCoordinate	图像中的地标坐标。
MaskProperties	描述给定人脸上存在掩码的属性。
MaskType	掩码的类型。
NoiseLevel	指示干扰级别。
NoiseProperties	描述图像噪音级别的属性。
OcclusionProperties	描述给定人脸上遮挡的属性。
QualityForRecognition	指示用于识别的图像质量。
RecognitionModel	人脸的识别模型。

AccessoryItem

附件项和相应的置信度。

名称	类型	说明
confidence	number	附件类型的置信度级别。介于 [0,1] 之间。
type	AccessoryType	附件的类型。

AccessoryType

附件的类型。

名称	类型	说明
glasses	string	眼镜。
headwear	string	头戴。
mask	string	面具。

BlurLevel

指示模糊程度。

名称	类型	说明
high	string	高模糊级别。
low	string	低模糊级别。
medium	string	中等模糊级别。

BlurProperties

描述图像中存在模糊状态的属性。

名称	类型	说明
blurLevel	BlurLevel	一个指示模糊级别的枚举值。
value	number	一个数字，指示模糊级别从 0 到 1。

DetectionModel

与检测到的 faceId 关联的“detectionModel”。支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。默认值为“detection_01”。

名称	类型	说明
detection_01	string	默认检测模型。建议用于近正面人脸检测。对于具有异常大角度（头部姿势）人脸、遮挡人脸或错误图像方向的方案，可能无法检测到此类情况下的人脸。
detection_02	string	检测模型于 2019 年 5 月发布，提高了准确性，尤其是在小面和模糊的脸上。
detection_03	string	2021 年 2 月发布的检测模型，提高了准确性，尤其是在小脸上。

ExposureLevel

指示曝光级别。

名称	类型	说明
goodExposure	string	良好的曝光级别。
overExposure	string	高曝光级别。
underExposure	string	低曝光级别。

ExposureProperties

描述图像曝光级别的属性。

名称	类型	说明
exposureLevel	ExposureLevel	指示曝光级别的枚举值。
value	number	一个数字，指示曝光级别范围为 0 到 1。 [0， 0.25）处于曝光之下。 [0.25， 0.75）曝光良好。 [0.75， 1] 暴露过度。

FaceAttributes

检测到的人脸的人脸属性。

名称	类型	说明
accessories	AccessoryItem[]	描述给定人脸上任何配件的属性。
age	number	年龄在岁。
blur	BlurProperties	描述图像中存在模糊状态的属性。
exposure	ExposureProperties	描述图像曝光级别的属性。
facialHair	FacialHair	描述面部头发属性的属性。
glasses	GlassesType	眼镜类型（如果任何人脸）。
hair	HairProperties	描述头发属性的属性。
headPose	HeadPose	3D 滚/偏航/俯仰角度用于人脸方向。
mask	MaskProperties	描述给定人脸上存在掩码的属性。
noise	NoiseProperties	描述图像噪音级别的属性。
occlusion	OcclusionProperties	描述给定人脸上遮挡的属性。
qualityForRecognition	QualityForRecognition	描述在检测中使用的图像的整体图像质量的属性是否具有足够的质量来尝试进行人脸识别。
smile	number	微笑强度，介于 [0,1] 之间的数字。

FaceAttributeType

分析和返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=headPose，眼镜”。人脸属性分析具有额外的计算和时间成本。

名称	类型	说明
accessories	string	脸周围的配件，包括“头饰”、“眼镜”和“面具”。空数组表示未检测到任何附件。请注意，这是检测到人脸之后。大掩码可能导致无法检测到人脸。
age	string	年龄在岁。
blur	string	人脸模糊不明确。级别返回“Low”、“Medium”或“High”。值返回介于 [0,1] 之间的数字，越模糊越大。
exposure	string	人脸曝光级别。级别返回“GoodExposure”、“OverExposure”或“UnderExposure”。
facialHair	string	描述面部头发属性的属性。
glasses	string	眼镜类型。值包括“NoGlasses”、“ReadingGlasses”、“Sunglasses”、“SwimmingGoggles”。
hair	string	描述头发属性的属性。
headPose	string	3D 滚/偏航/俯仰角度用于人脸方向。
mask	string	每个脸是否都戴着面具。掩码类型返回“noMask”、“faceMask”、“otherMaskOrOcclusion”或“不确定”。值返回一个布尔值“noseAndMouthCovered”，指示鼻子和嘴是否覆盖。
noise	string	人脸像素的噪音级别。级别返回“Low”、“Medium”和“High”。值返回一个介于 [0,1] 之间的数字，大于 noisier
occlusion	string	每个面部区域是否被遮挡，包括额头、眼睛和嘴。
qualityForRecognition	string	有关检测中使用的图像的整体图像质量是否足够，无法尝试进行人脸识别。该值是低、中或高非正式评级。对于识别方案，仅建议使用“高质量”图像进行人员注册，并且建议使用“中等”质量图像。仅当使用识别模型recognition_03或recognition_04时，该属性才可用。
smile	string	微笑强度，介于 [0,1] 之间的数字。

FaceDetectionResult

检测 API 的响应。

名称	类型	说明
faceAttributes	FaceAttributes	检测到的人脸的人脸属性。
faceId	string	检测到的人脸的唯一 faceId，由检测 API 创建，并在检测调用后 24 小时过期。若要返回此值，它要求“returnFaceId”参数为 true。
faceLandmarks	FaceLandmarks	一个由 27 磅人脸特征点构成的数组，指向人脸组件的重要位置。若要返回此值，它要求“returnFaceLandmarks”参数为 true。
faceRectangle	FaceRectangle	图像上人脸位置的矩形区域。
recognitionModel	RecognitionModel	与此 faceId 关联的“recognitionModel”。仅当“returnRecognitionModel”显式设置为 true 时，才会返回此值。

FaceError

错误对象。有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
message	string	错误的人工可读表示形式。

FaceErrorResponse

包含错误详细信息的响应。

名称	类型	说明
error	FaceError	错误对象。

FaceLandmarks

27 磅人脸特征点的集合，指向人脸组件的重要位置。

名称	类型	说明
eyeLeftBottom	LandmarkCoordinate	左眼底部的坐标。
eyeLeftInner	LandmarkCoordinate	左眼内部的坐标。
eyeLeftOuter	LandmarkCoordinate	左眼外侧的坐标。
eyeLeftTop	LandmarkCoordinate	左眼顶部的坐标。
eyeRightBottom	LandmarkCoordinate	右眼底部的坐标。
eyeRightInner	LandmarkCoordinate	右眼内部的坐标。
eyeRightOuter	LandmarkCoordinate	右眼外侧的坐标。
eyeRightTop	LandmarkCoordinate	右眼顶部的坐标。
eyebrowLeftInner	LandmarkCoordinate	左眉毛内部的坐标。
eyebrowLeftOuter	LandmarkCoordinate	左眉毛外部的坐标。
eyebrowRightInner	LandmarkCoordinate	右眉心内部的坐标。
eyebrowRightOuter	LandmarkCoordinate	右眉毛外部的坐标。
mouthLeft	LandmarkCoordinate	嘴左坐标。
mouthRight	LandmarkCoordinate	右嘴的坐标。
noseLeftAlarOutTip	LandmarkCoordinate	鼻子的坐标左尖。
noseLeftAlarTop	LandmarkCoordinate	鼻子左上角的坐标。
noseRightAlarOutTip	LandmarkCoordinate	鼻子右尖的坐标。
noseRightAlarTop	LandmarkCoordinate	鼻子右上部的坐标。
noseRootLeft	LandmarkCoordinate	左鼻根的坐标。
noseRootRight	LandmarkCoordinate	鼻子根右侧的坐标。
noseTip	LandmarkCoordinate	鼻尖的坐标。
pupilLeft	LandmarkCoordinate	左眼学生的坐标。
pupilRight	LandmarkCoordinate	右眼学生的坐标。
underLipBottom	LandmarkCoordinate	下唇底部的坐标。
underLipTop	LandmarkCoordinate	下唇顶部的坐标。
upperLipBottom	LandmarkCoordinate	上唇底部的坐标。
upperLipTop	LandmarkCoordinate	上唇顶的坐标。

FaceRectangle

在其中可以找到人脸的矩形。

名称	类型	说明
height	integer	矩形的高度（以像素为单位）。
left	integer	如果图像到矩形左边缘（以像素为单位）的距离。
top	integer	图像到矩形上边缘（以像素为单位）的距离。
width	integer	矩形的宽度（以像素为单位）。

FacialHair

描述面部头发属性的属性。

名称	类型	说明
beard	number	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
moustache	number	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
sideburns	number	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。

GlassesType

眼镜类型的人脸。

名称	类型	说明
noGlasses	string	脸上没有眼镜。
readingGlasses	string	脸上的正常眼镜。
sunglasses	string	脸上的太阳镜。
swimmingGoggles	string	脸上的游泳护目镜。

HairColor

候选颜色和置信度数组，存在于每个颜色和置信度中。

名称	类型	说明
color	HairColorType	头发颜色的名称。
confidence	number	颜色的置信度。介于 [0,1] 之间。

HairColorType

头发颜色的名称。

名称	类型	说明
black	string	黑。
blond	string	金发。
brown	string	棕色。
gray	string	灰色。
other	string	其他。
red	string	红。
unknown	string	未知。
white	string	白。

HairProperties

描述头发属性的属性。

名称	类型	说明
bald	number	一个数字，描述人员是否秃顶的置信度。
hairColor	HairColor[]	候选颜色和置信度数组，存在于每个颜色和置信度中。
invisible	boolean	描述头发是否在图像中可见的布尔值。

HeadPose

3D 滚/偏航/俯仰角度用于人脸方向。

名称	类型	说明
pitch	number	角度的值。
roll	number	角度的值。
yaw	number	角度的值。

LandmarkCoordinate

图像中的地标坐标。

名称	类型	说明
x	number	水平分量（以像素为单位）。
y	number	垂直组件（以像素为单位）。

MaskProperties

描述给定人脸上存在掩码的属性。

名称	类型	说明
noseAndMouthCovered	boolean	一个布尔值，该值指示鼻子和嘴是否覆盖。
type	MaskType	掩码的类型。

MaskType

掩码的类型。

名称	类型	说明
faceMask	string	面具。
noMask	string	无掩码。
otherMaskOrOcclusion	string	其他类型的掩码或遮挡。
uncertain	string	不确定性。

NoiseLevel

指示干扰级别。

名称	类型	说明
high	string	高噪音级别。
low	string	低噪音级别。
medium	string	中等噪音级别。

NoiseProperties

描述图像噪音级别的属性。

名称	类型	说明
noiseLevel	NoiseLevel	指示干扰级别的枚举值。
value	number	一个数字，指示干扰级别范围为 0 到 1。 [0， 0.25）处于曝光之下。 [0.25， 0.75）曝光良好。 [0.75， 1] 暴露过度。 [0， 0.3）是低噪音级别。 [0.3， 0.7）为中等噪音级别。 [0.7， 1] 是高噪音级别。

OcclusionProperties

描述给定人脸上遮挡的属性。

名称	类型	说明
eyeOccluded	boolean	一个布尔值，该值指示眼睛是否被遮挡。
foreheadOccluded	boolean	一个布尔值，该值指示额头是否被遮挡。
mouthOccluded	boolean	一个布尔值，该值指示嘴是否被遮挡。

QualityForRecognition

指示用于识别的图像质量。

名称	类型	说明
high	string	高质量。
low	string	质量低。
medium	string	中等质量。

RecognitionModel

人脸的识别模型。

名称	类型	说明
recognition_01	string	“Detect”的默认识别模型。 2019 年 3 月之前创建的所有 faceId 都与此识别模型绑定在一起。
recognition_02	string	识别模型于 2019 年 3 月发布。
recognition_03	string	识别模型于 2020 年 5 月发布。
recognition_04	string	识别模型于 2021 年 2 月发布。建议使用此识别模型来提高识别准确性。

通过

Face Detection Operations - Detect From Url

URI 参数

请求正文

响应

安全性

Ocp-Apim-Subscription-Key

AADToken

作用域

示例

Detect with Image URL

示例请求

示例响应

定义

AccessoryItem

AccessoryType

BlurLevel

BlurProperties

DetectionModel

ExposureLevel

ExposureProperties

FaceAttributes

FaceAttributeType

FaceDetectionResult

FaceError

FaceErrorResponse

FaceLandmarks

FaceRectangle

FacialHair

GlassesType

HairColor

HairColorType

HairProperties

HeadPose

LandmarkCoordinate

MaskProperties

MaskType

NoiseLevel

NoiseProperties

OcclusionProperties

QualityForRecognition

RecognitionModel

其他资源