共用方式為


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

快取臉部標識碼的秒數。 支援的範圍從 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,glasses'。 臉部屬性分析具有額外的計算和時間成本。

returnFaceId
query

boolean

傳回所偵測到臉部的faceId。 默認值為 true。

returnFaceLandmarks
query

boolean

傳回偵測到臉部的臉部地標。 默認值為 false。

returnRecognitionModel
query

boolean

傳回 'recognitionModel' 或否。 默認值為 false。 只有在 returnFaceId = true 時才適用。

要求本文

Media Types: "application/octet-stream"

名稱 類型 Description
imageContent

string

輸入影像二進位檔。

回應

名稱 類型 Description
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
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

名稱 Description
https://cognitiveservices.azure.com/.default

範例

Detect with Image

Sample request

POST {endpoint}/face/v1.1-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>"

Sample response

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

配件項目和對應的信賴等級。

AccessoryType

配件的類型。

BlurLevel

表示模糊程度。

BlurProperties

描述影像中任何模糊狀態的屬性。

DetectionModel

與偵測到的faceId相關聯的 'detectionModel'。 支援的 'detectionModel' 值包括 'detection_01'、'detection_02' 和 'detection_03'。 預設值為 『detection_01』。

ExposureLevel

表示曝光層級。

ExposureProperties

描述影像曝光層級的屬性。

FaceAttributes

偵測到臉部的臉部屬性。

FaceAttributeType

分析並傳回逗號分隔字串中的一或多個指定臉部屬性,例如 'returnFaceAttributes=headPose,glasses'。 臉部屬性分析具有額外的計算和時間成本。

FaceDetectionResult

偵測 API 的回應。

FaceError

error 物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據,請參閱下列連結: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

配件項目和對應的信賴等級。

名稱 類型 Description
confidence

number

配件類型的信賴等級。 範圍介於 [0,1]。

type

AccessoryType

配件的類型。

AccessoryType

配件的類型。

名稱 類型 Description
glasses

string

眼鏡。

headwear

string

頭戴。

mask

string

面具。

BlurLevel

表示模糊程度。

名稱 類型 Description
high

string

高模糊等級。

low

string

低模糊層級。

medium

string

中模糊層級。

BlurProperties

描述影像中任何模糊狀態的屬性。

名稱 類型 Description
blurLevel

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

ExposureLevel

列舉值,表示曝光程度。

value

number

數位,表示曝光等級從 0 到 1。 [0, 0.25) 正在曝光。 [0.25, 0.75) 是良好的曝光。 [0.75, 1] 超過曝光。

FaceAttributes

偵測到臉部的臉部屬性。

名稱 類型 Description
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,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

FaceAttributes

偵測到臉部的臉部屬性。

faceId

string

偵測 API 所建立之偵測臉部的唯一 faceId,且會在偵測呼叫之後 24 小時到期。 若要傳回此專案,它需要 『returnFaceId』 參數為 true。

faceLandmarks

FaceLandmarks

27 點臉部地標的數位,指向臉部元件的重要位置。 若要傳回此專案,它需要 『returnFaceLandmarks』 參數為 true。

faceRectangle

FaceRectangle

影像上臉部位置的矩形區域。

recognitionModel

RecognitionModel

與此faceId相關聯的 『recognitionModel』。 只有當 'returnRecognitionModel' 明確設定為 true 時,才會傳回這個值。

FaceError

error 物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據,請參閱下列連結:https://aka.ms/face-error-codes-and-messages

名稱 類型 Description
code

string

其中一組伺服器定義的錯誤碼。

message

string

錯誤的人類可讀取表示法。

FaceErrorResponse

包含錯誤詳細數據的回應。

名稱 類型 Description
error

FaceError

error 物件。

FaceLandmarks

27 點臉部地標的集合,指向臉部元件的重要位置。

名稱 類型 Description
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

可以在其中找到臉部的矩形。

名稱 類型 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

HairColorType

頭髮色彩的名稱。

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

HairColor[]

每個候選色彩和信賴等級的陣列。

invisible

boolean

布爾值,描述影像中是否顯示頭髮。

HeadPose

面向方向的 3D 滾/偏轉/傾斜角度。

名稱 類型 Description
pitch

number

角度的值。

roll

number

角度的值。

yaw

number

角度的值。

LandmarkCoordinate

影像中的地標座標。

名稱 類型 Description
x

number

水平元件,以像素為單位。

y

number

垂直元件,以像素為單位。

MaskProperties

描述指定臉部上遮罩存在的屬性。

名稱 類型 Description
noseAndMouthCovered

boolean

布爾值,指出鼻子和嘴是否覆蓋。

type

MaskType

遮罩的類型。

MaskType

遮罩的類型。

名稱 類型 Description
faceMask

string

面具。

noMask

string

沒有遮罩。

otherMaskOrOcclusion

string

其他類型的遮罩或遮蔽。

uncertain

string

不確定性。

NoiseLevel

表示雜訊層級。

名稱 類型 Description
high

string

高雜訊等級。

low

string

低雜訊等級。

medium

string

中雜訊等級。

NoiseProperties

描述影像雜訊等級的屬性。

名稱 類型 Description
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

描述指定臉部遮蔽的屬性。

名稱 類型 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 月發行。 建議您使用此辨識模型來提升辨識精確度。