Face Detection Operations - Detect
偵測影像中的人臉、傳回臉部矩形,以及選擇性地使用faceId、地標和屬性。
重要
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。
- 影像中可偵測到的臉部大小下限為 36x36 像素,不大於 1920x1080 圖元。 維度高於 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' 值。 如果需要「驗證」、「識別」、「尋找類似專案」等後續作業,請使用 『recognitionModel』 參數來指定辨識模型。 'recognitionModel' 的預設值為 'recognition_01',如果需要最新的模型,請明確指定此參數中所需的模型。 指定之後,偵測到的faceIds將會與指定的辨識模型相關聯。 如需詳細資訊,請參閱 https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-recognition-model。
POST {endpoint}/face/{apiVersion}/detect
POST {endpoint}/face/{apiVersion}/detect?_overload=detect&detectionModel={detectionModel}&recognitionModel={recognitionModel}&returnFaceId={returnFaceId}&returnFaceAttributes={returnFaceAttributes}&returnFaceLandmarks={returnFaceLandmarks}&returnRecognitionModel={returnRecognitionModel}&faceIdTimeToLive={faceIdTimeToLive}
URI 參數
名稱 | 位於 | 必要 | 類型 | Description |
---|---|---|---|---|
api
|
path | True |
string |
API 版本 |
endpoint
|
path | True |
string uri |
支持的認知服務端點(通訊協定和主機名,例如:https://{resource-name}.cognitiveservices.azure.com)。 |
detection
|
query |
與偵測到的faceId相關聯的 'detectionModel'。 支援的 'detectionModel' 值包括 'detection_01'、'detection_02' 和 'detection_03'。 預設值為 『detection_01』。 |
||
face
|
query |
integer int32 |
快取臉部標識碼的秒數。 支援的範圍從 60 秒到 86400 秒。 默認值為86400 (24小時)。 |
|
recognition
|
query |
與偵測到的 faceId 相關聯的 『recognitionModel』。 支援的 'recognitionModel' 值包括 'recognition_01'、'recognition_02'、'recognition_03' 或 'recognition_04'。 預設值為 『recognition_01』。 建議使用『recognition_04』,因為它的精確度比“recognition_03”來改善臉部的精確度,而且與“recognition_01”和“recognition_02”相比,其整體精確度也得到了改善。 |
||
return
|
query |
分析並傳回逗號分隔字串中的一或多個指定臉部屬性,例如 'returnFaceAttributes=headPose,glasses'。 臉部屬性分析具有額外的計算和時間成本。 |
||
return
|
query |
boolean |
傳回所偵測到臉部的faceId。 默認值為 true。 |
|
return
|
query |
boolean |
傳回偵測到臉部的臉部地標。 默認值為 false。 |
|
return
|
query |
boolean |
傳回 'recognitionModel' 或否。 默認值為 false。 只有在 returnFaceId = true 時才適用。 |
要求本文
Media Types: "application/octet-stream"
名稱 | 類型 | Description |
---|---|---|
imageContent |
string |
輸入影像二進位檔。 |
回應
名稱 | 類型 | Description |
---|---|---|
200 OK |
成功的呼叫會傳回以遞減順序依臉部矩形大小排名的臉部項目陣列。 空的回應表示未偵測到臉部。 |
|
Other Status Codes |
未預期的錯誤回應。 標題 x-ms-error-code: string |
安全性
Ocp-Apim-Subscription-Key
Azure AI 臉部訂用帳戶的秘密密鑰。
類型:
apiKey
位於:
header
AADToken
Azure Active Directory OAuth2 流程
類型:
oauth2
Flow:
accessCode
授權 URL:
https://api.example.com/oauth2/authorize
權杖 URL:
https://api.example.com/oauth2/token
範圍
名稱 | Description |
---|---|
https://cognitiveservices.azure.com/.default |
範例
Detect with Image
範例要求
POST {endpoint}/face/v1.2-preview.1/detect?_overload=detect&detectionModel=detection_01&recognitionModel=recognition_03&returnFaceId=True&returnFaceAttributes=glasses,headPose,occlusion,accessories,blur,exposure,noise,qualityForRecognition&returnFaceLandmarks=True&returnRecognitionModel=True&faceIdTimeToLive=60
"<your-image-bytes-here>"
範例回覆
[
{
"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"
}
}
]
定義
名稱 | Description |
---|---|
Accessory |
配件項目和對應的信賴等級。 |
Accessory |
配件的類型。 |
Blur |
表示模糊程度。 |
Blur |
描述影像中任何模糊狀態的屬性。 |
Detection |
與偵測到的faceId相關聯的 'detectionModel'。 支援的 'detectionModel' 值包括 'detection_01'、'detection_02' 和 'detection_03'。 預設值為 『detection_01』。 |
Exposure |
表示曝光層級。 |
Exposure |
描述影像曝光層級的屬性。 |
Face |
偵測到臉部的臉部屬性。 |
Face |
分析並傳回逗號分隔字串中的一或多個指定臉部屬性,例如 'returnFaceAttributes=headPose,glasses'。 臉部屬性分析具有額外的計算和時間成本。 |
Face |
偵測 API 的回應。 |
Face |
error 物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據,請參閱下列連結:https://aka.ms/face-error-codes-and-messages。 |
Face |
包含錯誤詳細數據的回應。 |
Face |
27 點臉部地標的集合,指向臉部元件的重要位置。 |
Face |
可以在其中找到臉部的矩形。 |
Facial |
描述臉部頭髮屬性的屬性。 |
Glasses |
眼鏡類型。 |
Hair |
每個候選色彩和信賴等級的陣列。 |
Hair |
頭髮色彩的名稱。 |
Hair |
描述頭髮屬性的屬性。 |
Head |
面向方向的 3D 滾/偏轉/傾斜角度。 |
Landmark |
影像中的地標座標。 |
Mask |
描述指定臉部上遮罩存在的屬性。 |
Mask |
遮罩的類型。 |
Noise |
表示雜訊層級。 |
Noise |
描述影像雜訊等級的屬性。 |
Occlusion |
描述指定臉部遮蔽的屬性。 |
Quality |
表示影像的辨識品質。 |
Recognition |
臉部的辨識模型。 |
AccessoryItem
配件項目和對應的信賴等級。
名稱 | 類型 | Description |
---|---|---|
confidence |
number |
配件類型的信賴等級。 範圍介於 [0,1]。 |
type |
配件的類型。 |
AccessoryType
配件的類型。
名稱 | 類型 | Description |
---|---|---|
glasses |
string |
眼鏡。 |
headwear |
string |
頭戴。 |
mask |
string |
面具。 |
BlurLevel
表示模糊程度。
名稱 | 類型 | Description |
---|---|---|
high |
string |
高模糊等級。 |
low |
string |
低模糊層級。 |
medium |
string |
中模糊層級。 |
BlurProperties
描述影像中任何模糊狀態的屬性。
名稱 | 類型 | Description |
---|---|---|
blurLevel |
列舉值,表示模糊程度。 |
|
value |
number |
數位,表示模糊程度從 0 到 1。 |
DetectionModel
與偵測到的faceId相關聯的 'detectionModel'。 支援的 'detectionModel' 值包括 'detection_01'、'detection_02' 和 'detection_03'。 預設值為 『detection_01』。
名稱 | 類型 | Description |
---|---|---|
detection_01 |
string |
默認偵測模型。 建議用於近距離正面偵測。 對於具有特殊大角度(頭部姿勢)臉部、遮蔽臉部或錯誤影像方向的案例,可能無法偵測到這類情況下的臉部。 |
detection_02 |
string |
偵測模型於 2019 年 5 月發行,精確度更高,特別是在小型、側邊和模糊的臉部上。 |
detection_03 |
string |
偵測模型於 2021 年 2 月發行,精確度更高,特別是在小臉上。 |
ExposureLevel
表示曝光層級。
名稱 | 類型 | Description |
---|---|---|
goodExposure |
string |
良好的曝光水準。 |
overExposure |
string |
高曝光程度。 |
underExposure |
string |
低暴露程度。 |
ExposureProperties
描述影像曝光層級的屬性。
名稱 | 類型 | Description |
---|---|---|
exposureLevel |
列舉值,表示曝光程度。 |
|
value |
number |
數位,表示曝光等級從 0 到 1。 [0, 0.25) 正在曝光。 [0.25, 0.75) 是良好的曝光。 [0.75, 1] 超過曝光。 |
FaceAttributes
偵測到臉部的臉部屬性。
名稱 | 類型 | Description |
---|---|---|
accessories |
描述指定臉部上任何配件的屬性。 |
|
age |
number |
年齡在歲。 |
blur |
描述影像中任何模糊狀態的屬性。 |
|
exposure |
描述影像曝光層級的屬性。 |
|
facialHair |
描述臉部頭髮屬性的屬性。 |
|
glasses |
眼鏡輸入,如果任何一個臉。 |
|
hair |
描述頭髮屬性的屬性。 |
|
headPose |
面向方向的 3D 滾/偏轉/傾斜角度。 |
|
mask |
描述指定臉部上遮罩存在的屬性。 |
|
noise |
描述影像雜訊等級的屬性。 |
|
occlusion |
描述指定臉部遮蔽的屬性。 |
|
qualityForRecognition |
描述偵測中使用影像的整體影像品質的屬性是否有足夠的品質,可嘗試進行臉部辨識。 |
|
smile |
number |
微笑強度,介於 [0,1] 之間的數位。 |
FaceAttributeType
分析並傳回逗號分隔字串中的一或多個指定臉部屬性,例如 'returnFaceAttributes=headPose,glasses'。 臉部屬性分析具有額外的計算和時間成本。
名稱 | 類型 | Description |
---|---|---|
accessories |
string |
臉部周圍的配件,包括“頭飾”、“眼鏡”和“面具”。 空陣列表示未偵測到任何配件。 請注意,這是偵測到臉部之後。 大型遮罩可能會導致無法偵測到任何臉部。 |
age |
string |
年齡在歲。 |
blur |
string |
臉部模糊不明確。 層級會傳回 'Low'、'Medium' 或 'High'。 值會傳回介於 [0,1] 之間的數位,越模糊越大。 |
exposure |
string |
臉部暴露程度。 Level 會傳回 'GoodExposure'、'OverExposure' 或 'UnderExposure'。 |
facialHair |
string |
描述臉部頭髮屬性的屬性。 |
glasses |
string |
眼鏡類型。 值包括 『NoGlasses』、『ReadingGlasses』、『Sunglasses』、'SwimmingGoggles'。 |
hair |
string |
描述頭髮屬性的屬性。 |
headPose |
string |
面向方向的 3D 滾/偏轉/傾斜角度。 |
mask |
string |
每張臉是否都戴著面具。 遮罩類型會傳回 'noMask'、'faceMask'、'otherMaskOrOcclusion' 或 'uncertain'。 值會傳回布爾值 『noseAndMouthCovered』,指出鼻子和嘴是否覆蓋。 |
noise |
string |
臉部圖元的雜訊等級。 層級會傳回 'Low'、'Medium' 和 'High'。 值會傳回介於 [0,1] 之間的數位,較大型的 noisier |
occlusion |
string |
每個面部區域是否被遮蔽,包括額頭、眼睛和嘴。 |
qualityForRecognition |
string |
在偵測中使用的影像是否具有足夠的品質,以嘗試進行臉部辨識的整體影像品質。 此值是低、中或高非正式評等。 只有「高」品質的影像建議用於人員註冊,建議在識別案例中使用「中型」或更新版本的品質。 只有在使用辨識模型recognition_03或recognition_04時,才能使用 屬性。 |
smile |
string |
微笑強度,介於 [0,1] 之間的數位。 |
FaceDetectionResult
偵測 API 的回應。
名稱 | 類型 | Description |
---|---|---|
faceAttributes |
偵測到臉部的臉部屬性。 |
|
faceId |
string |
偵測 API 所建立之偵測臉部的唯一 faceId,且會在偵測呼叫之後 24 小時到期。 若要傳回此專案,它需要 『returnFaceId』 參數為 true。 |
faceLandmarks |
27 點臉部地標的數位,指向臉部元件的重要位置。 若要傳回此專案,它需要 『returnFaceLandmarks』 參數為 true。 |
|
faceRectangle |
影像上臉部位置的矩形區域。 |
|
recognitionModel |
與此faceId相關聯的 『recognitionModel』。 只有當 'returnRecognitionModel' 明確設定為 true 時,才會傳回這個值。 |
FaceError
error 物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據,請參閱下列連結:https://aka.ms/face-error-codes-and-messages。
名稱 | 類型 | Description |
---|---|---|
code |
string |
其中一組伺服器定義的錯誤碼。 |
message |
string |
錯誤的人類可讀取表示法。 |
FaceErrorResponse
包含錯誤詳細數據的回應。
名稱 | 類型 | Description |
---|---|---|
error |
error 物件。 |
FaceLandmarks
27 點臉部地標的集合,指向臉部元件的重要位置。
名稱 | 類型 | Description |
---|---|---|
eyeLeftBottom |
左眼底部的座標。 |
|
eyeLeftInner |
左眼內部的座標。 |
|
eyeLeftOuter |
左眼外部的座標。 |
|
eyeLeftTop |
左眼頂端的座標。 |
|
eyeRightBottom |
右眼底部的座標。 |
|
eyeRightInner |
右眼內部的座標。 |
|
eyeRightOuter |
右眼外部的座標。 |
|
eyeRightTop |
右眼頂端的座標。 |
|
eyebrowLeftInner |
左眉毛內部的座標。 |
|
eyebrowLeftOuter |
左眉毛外部的座標。 |
|
eyebrowRightInner |
右眉心內部的座標。 |
|
eyebrowRightOuter |
右眉毛外部的座標。 |
|
mouthLeft |
左嘴的座標。 |
|
mouthRight |
右嘴的座標。 |
|
noseLeftAlarOutTip |
鼻子的座標左大尖。 |
|
noseLeftAlarTop |
鼻子左上方的座標。 |
|
noseRightAlarOutTip |
鼻子右大尖的座標。 |
|
noseRightAlarTop |
鼻子右阿拉爾頂端的座標。 |
|
noseRootLeft |
左鼻子根的座標。 |
|
noseRootRight |
右鼻子根的座標。 |
|
noseTip |
鼻子尖的座標。 |
|
pupilLeft |
左眼學生的座標。 |
|
pupilRight |
右眼學生的座標。 |
|
underLipBottom |
下唇底的座標。 |
|
underLipTop |
下唇頂端的座標。 |
|
upperLipBottom |
上唇底部的座標。 |
|
upperLipTop |
上唇頂端的座標。 |
FaceRectangle
可以在其中找到臉部的矩形。
名稱 | 類型 | Description |
---|---|---|
height |
integer |
矩形的高度,以像素為單位。 |
left |
integer |
如果影像到矩形左邊緣的距離,以像素為單位。 |
top |
integer |
影像到矩形上邊緣的距離,以像素為單位。 |
width |
integer |
矩形的寬度,以像素為單位。 |
FacialHair
描述臉部頭髮屬性的屬性。
名稱 | 類型 | Description |
---|---|---|
beard |
number |
數位,範圍從 0 到 1,表示與 屬性相關聯的信賴等級。 |
moustache |
number |
數位,範圍從 0 到 1,表示與 屬性相關聯的信賴等級。 |
sideburns |
number |
數位,範圍從 0 到 1,表示與 屬性相關聯的信賴等級。 |
GlassesType
眼鏡類型。
名稱 | 類型 | Description |
---|---|---|
noGlasses |
string |
臉上沒有眼鏡。 |
readingGlasses |
string |
臉上的正常眼鏡。 |
sunglasses |
string |
臉上的太陽鏡。 |
swimmingGoggles |
string |
臉上游泳護目鏡。 |
HairColor
每個候選色彩和信賴等級的陣列。
名稱 | 類型 | Description |
---|---|---|
color |
頭髮色彩的名稱。 |
|
confidence |
number |
色彩的信賴等級。 範圍介於 [0,1]。 |
HairColorType
頭髮色彩的名稱。
名稱 | 類型 | Description |
---|---|---|
black |
string |
黑。 |
blond |
string |
金髮。 |
brown |
string |
棕色。 |
gray |
string |
灰色。 |
other |
string |
其他。 |
red |
string |
紅。 |
unknown |
string |
未知。 |
white |
string |
白。 |
HairProperties
描述頭髮屬性的屬性。
名稱 | 類型 | Description |
---|---|---|
bald |
number |
一個數位,描述人員是否禿頂的信賴等級。 |
hairColor |
每個候選色彩和信賴等級的陣列。 |
|
invisible |
boolean |
布爾值,描述影像中是否顯示頭髮。 |
HeadPose
面向方向的 3D 滾/偏轉/傾斜角度。
名稱 | 類型 | Description |
---|---|---|
pitch |
number |
角度的值。 |
roll |
number |
角度的值。 |
yaw |
number |
角度的值。 |
LandmarkCoordinate
影像中的地標座標。
名稱 | 類型 | Description |
---|---|---|
x |
number |
水平元件,以像素為單位。 |
y |
number |
垂直元件,以像素為單位。 |
MaskProperties
描述指定臉部上遮罩存在的屬性。
名稱 | 類型 | Description |
---|---|---|
noseAndMouthCovered |
boolean |
布爾值,指出鼻子和嘴是否覆蓋。 |
type |
遮罩的類型。 |
MaskType
遮罩的類型。
名稱 | 類型 | Description |
---|---|---|
faceMask |
string |
面具。 |
noMask |
string |
沒有遮罩。 |
otherMaskOrOcclusion |
string |
其他類型的遮罩或遮蔽。 |
uncertain |
string |
不確定性。 |
NoiseLevel
表示雜訊層級。
名稱 | 類型 | Description |
---|---|---|
high |
string |
高雜訊等級。 |
low |
string |
低雜訊等級。 |
medium |
string |
中雜訊等級。 |
NoiseProperties
描述影像雜訊等級的屬性。
名稱 | 類型 | Description |
---|---|---|
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
描述指定臉部遮蔽的屬性。
名稱 | 類型 | Description |
---|---|---|
eyeOccluded |
boolean |
布爾值,指出眼睛是否遮蔽。 |
foreheadOccluded |
boolean |
布爾值,指出前額是否遮蔽。 |
mouthOccluded |
boolean |
布爾值,指出嘴是否遮蔽。 |
QualityForRecognition
表示影像的辨識品質。
名稱 | 類型 | Description |
---|---|---|
high |
string |
高品質。 |
low |
string |
品質低。 |
medium |
string |
中等品質。 |
RecognitionModel
臉部的辨識模型。
名稱 | 類型 | Description |
---|---|---|
recognition_01 |
string |
「偵測」的預設辨識模型。 所有在 2019 年 3 月之前建立的 faceId 都會與這個辨識模型結合。 |
recognition_02 |
string |
辨識模型於 2019 年 3 月發行。 |
recognition_03 |
string |
辨識模型於 2020 年 5 月發行。 |
recognition_04 |
string |
辨識模型於 2021 年 2 月發行。 建議您使用此辨識模型來提升辨識精確度。 |