呼叫偵測 API

警告

臉部辨識服務存取受限於資格和使用準則，以支援我們的「負責任的 AI 原則」。 臉部辨識服務僅供 Microsoft 受管理的客戶和合作夥伴使用。 請使用臉部辨識受理表單以申請存取。 如需詳細資訊，請參閱臉部的有限存取權頁面。

警告

Microsoft 已淘汰或限制可用來試圖推斷情緒狀態和身分識別屬性的臉部辨識功能，此功能若使用不當，可能會使人們遭受刻板印象、歧視或不公平服務遭拒的影響。 淘汰的功能為情感和性別。 限制的功能為年齡、微笑、臉部毛髮、頭髮和化妝。 如果您有負責任的使用案例可受益於使用任何限制的功能，請傳送電子郵件給 Azure 臉部 API。 在這裡深入了解此決策。

本指南會示範如何使用臉部偵測 API，在指定的影像中擷取屬性。 您將了解各種設定此 API 行為的方式，以符合您的需求。

本指南中的程式碼片段是使用 Azure AI 的臉部用戶端程式庫，以 C# 撰寫。 相同的功能可透過 REST API 取得。

設定

本指南假設您使用臉部金鑰和端點 URL 建構名為 faceClient 的 FaceClient 物件。 如需如何設定這項功能的指示，請遵循其中一種快速入門。

將資料提交給服務

若要尋找臉部並取得其在影像中的位置，請呼叫 DetectAsync。 其接受 URL 字串或原始影像二進位檔做為輸入。

var response = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false);
IReadOnlyList<FaceDetectionResult> faces = response.Value;

服務會傳回 FaceDetectionResult 物件，您可以查詢下面指定的不同類型資訊。

如需如何剖析臉部位置和維度的資訊，請參閱 FaceRectangle。 這個矩形通常會包含眼睛、眉毛、鼻子和嘴巴。 額頭、耳朵和下巴則不一定包含在內。 若要使用臉部矩形裁剪完整的頭部或取得中景半身像，則應往每個方向展開矩形。

決定如何處理資料

本指南著重於偵測呼叫的詳細資料，例如可以傳遞的引數，以及可如何處理傳回的資料。 建議只查詢所需的功能。 每項作業都需要更多時間才能完成。

取得 Face ID

如果您將 returnFaceId 參數設定為 true (僅限核准的客戶)，則您可以取得每個臉部的唯一識別碼，以供稍後的臉部辨識工作使用。

foreach (var face in faces)
{
    string id = face.FaceId.ToString();
    FaceRectangle rect = face.FaceRectangle;
}

選擇性 faceIdTimeToLive 參數會指定 Face ID 應該儲存在伺服器上的時間 (以秒為單位)。 此時間到期之後，會移除 Face ID。 預設值為 86400 (24 小時)。

取得臉部特徵點

臉部特徵點是一組容易在臉上找到的點，例如瞳孔或鼻尖。 若要取得臉部特徵點資料，請將 detectionModel 參數設定為 FaceDetectionModel.Detection03，將 returnFaceLandmarks 參數設定為 true。

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
var response2 = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceLandmarks: true);
IReadOnlyList<FaceDetectionResult> faces2 = response2.Value;

取得臉部屬性

除了臉部矩形和特徵點外，臉部偵測 API 還會分析數個臉部的概念屬性。 如需完整清單，請參閱臉部屬性概念一節。

若要分析臉部屬性，請將 detectionModel 參數設定為 FaceDetectionModel.Detection03，將 returnFaceAttributes 參數設定為 FaceAttributeType Enum 值清單。

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.Detection03.Blur,
    FaceAttributeType.Detection03.HeadPose,
    FaceAttributeType.Detection03.Mask,
    FaceAttributeType.Recognition04.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var response3 = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes);
IReadOnlyList<FaceDetectionResult> faces3 = response3.Value;

取得服務的結果

臉部特徵點結果

下列程式碼示範如何擷取鼻子和瞳孔的位置：

foreach (var face in faces2)
{
    var landmarks = face.FaceLandmarks;

    double noseX = landmarks.NoseTip.X;
    double noseY = landmarks.NoseTip.Y;

    double leftPupilX = landmarks.PupilLeft.X;
    double leftPupilY = landmarks.PupilLeft.Y;

    double rightPupilX = landmarks.PupilRight.X;
    double rightPupilY = landmarks.PupilRight.Y;

您也可以使用臉部特徵點資料，精確計算臉部的朝向。 例如，您可以將臉部的旋轉定義為從嘴巴中心點到雙眼中心點的向量。 下列程式碼會計算這個向量：

    var upperLipBottom = landmarks.UpperLipBottom;
    var underLipTop = landmarks.UnderLipTop;

    var centerOfMouth = new Point(
        (int)((upperLipBottom.X + underLipTop.X) / 2),
        (int)((upperLipBottom.Y + underLipTop.Y) / 2));

    var eyeLeftInner = landmarks.EyeLeftInner;
    var eyeRightInner = landmarks.EyeRightInner;

    var centerOfTwoEyes = new Point(
        (int)((eyeLeftInner.X + eyeRightInner.X) / 2),
        (int)((eyeLeftInner.Y + eyeRightInner.Y) / 2));

    var faceDirectionVectorX = centerOfTwoEyes.X - centerOfMouth.X;
    var faceDirectionVectorY = centerOfTwoEyes.Y - centerOfMouth.Y;
}

知道臉部的方向後，您即可旋轉矩形臉部框以更正確地校正。 若要裁剪影像中的臉部，您可以用程式設計方式旋轉影像，讓臉部一律以直立的方式出現。

臉部屬性結果

下列程式碼會示範如何擷取您在原始呼叫中要求的臉部屬性資料。

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var blur = attributes.Blur;
    var headPose = attributes.HeadPose;
    var mask = attributes.Mask;
    var qualityForRecognition = attributes.QualityForRecognition;
}

若要深入了解每個屬性，請參閱臉部偵測和屬性概念指南。

下一步

在本指南中，您已了解如何使用臉部偵測和分析的各種功能。 接下來，將這些功能整合到應用程式，新增使用者的臉部資料。

• 教學課程：將使用者新增至臉部辨識服務

相關文章

• 參考文件 (REST)
• 參考文件 (.NET SDK)