呼叫偵測 API

警告

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

警告

Microsoft 已淘汰可用來試圖推斷情緒狀態和身分識別屬性的臉部辨識功能，此功能若使用不當，可能會使人們遭受刻板印象、歧視或不公平阻斷服務的影響。 其中包括可預測表情、性別、年齡、笑臉、臉部毛髮、頭髮和化妝品的功能。 在這裡深入了解此決策。

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

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

設定

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

將資料提交給服務

若要尋找臉部並取得其在影像中的位置，請呼叫 DetectWithUrlAsync 或 DetectWithStreamAsync 方法。 DetectWithUrlAsync 會將 URL 字串當作輸入，而 DetectWithStreamAsync 則會將影像的原始位元組資料流當作輸入。

IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, detectionModel: DetectionModel.Detection03);

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

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

決定如何處理資料

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

取得臉部標識碼

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

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

選擇性 faceIdTimeToLive 參數會指定臉部標識碼應該儲存在伺服器上的時間長度（以秒為單位）。 此時間到期之後，會移除臉部標識碼。 默認值為86400 （24小時）。

取得臉部特徵點

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

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
IList<DetectedFace> faces2 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceLandmarks: true, detectionModel: DetectionModel.Detection01);

取得臉部屬性

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

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

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.HeadPose,
    FaceAttributeType.Glasses,
    FaceAttributeType.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var faces3 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes, detectionModel: DetectionModel.Detection01, recognitionModel: RecognitionModel.Recognition04);

取得服務的結果

臉部特徵點結果

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

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(
        (upperLipBottom.X + underLipTop.X) / 2,
        (upperLipBottom.Y + underLipTop.Y) / 2);

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

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

    Vector faceDirection = new Vector(
        centerOfTwoEyes.X - centerOfMouth.X,
        centerOfTwoEyes.Y - centerOfMouth.Y);
}

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

臉部屬性結果

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

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    var qualityForRecognition = attributes.QualityForRecognition;
}

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

下一步

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

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

相關文章

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