Face API cURL 퀵 스타트

등록일시: 2017-12-19 08:00,  수정일시: 2018-04-08 05:49
조회수: 3,697
이 문서는 Cognitive Services 기술을 널리 알리고자 하는 개인적인 취지로 제공되는 번역문서입니다. 이 문서에 대한 모든 저작권은 마이크로소프트에 있으며 요청이 있을 경우 언제라도 게시가 중단될 수 있습니다. 번역 내용에 오역이 존재할 수 있고 주석은 번역자 개인의 의견일 뿐이며 마이크로소프트는 이에 관한 어떠한 보장도 하지 않습니다. 번역이 완료된 이후에도 대상 제품 및 기술이 개선되거나 변경됨에 따라 원문의 내용도 변경되거나 보완되었을 수 있으므로 주의하시기 바랍니다.
본문에서는 cURL 도구를 사용해서 Face API를 사용하는 방법을 살펴봅니다.

본문에서는 cURL과 Face API를 사용해서 다음과 같은 작업을 신속하게 수행하기 위해 필요한 유용한 정보와 예제 코드를 제공합니다:

무료 구독 키를 발급받는 방법은 구독 키 발급받기 문서를 참고하시기 바랍니다.

역주

본문에서는 본격적인 프로그래밍 언어를 사용해서 Face API를 사용하는 방법을 살펴보기에 앞서, 먼저 cURL이라는 명령줄 도구를 사용합니다. 이 도구에 친숙하지 않은 분들을 위해서 간단히 설명드리면 다양한 프로토콜을 이용해서 통신을 수행하는, 마치 Fiddler 같은 역할을 하는 명령줄 도구라고 생각하시면 이해가 쉽습니다. HTTP, HTTPS, FTP, FTPS, Gopher, IMAP, IMAPS 등 수십 여 가지에 달하는 프로토콜을 지원하고, 다양한 운영 체제에서 사용할 수 있기 때문에 본격적인 코드를 작성하기에 앞서 테스트를 해보거나 API의 응답 내역 등을 확인하는 작업에 유용합니다.

cURL에 대한 보다 자세한 정보는 공식 홈페이지위키피디아를 참고하시기 바랍니다. 또한 cURL의 한글 메뉴얼과 설치 방법 등은 정광섭님이 정리하신 curl 설치 및 사용법 - HTTP GET/POST, REST API 연계등 문서를 추천드립니다. 특히 해당 문서의 설치 절을 참고하시면 Windows용으로 빌드된 cURL을 다운로드 받을 수 있는 위치를 알 수 있습니다.

cURL을 이용해서 Face API로 이미지의 얼굴 감지하기

Face - Detect 메서드를 이용해서 이미지의 얼굴을 감지하고 다음과 같은 얼굴 특징을 반환받습니다:

  • 얼굴 ID: 다양한 Face API 시나리오에서 사용되는 얼굴의 고유 ID
  • 얼굴 사각형: 이미지 내의 얼굴 위치를 나타내는 Left, Top, Width, Height
  • 랜드마크: 얼굴 구성 요소의 중요한 위치를 나타내는 27 곳의 얼굴 랜드마크 배열
  • 나이, 성별, 미소짓는 정도, 머리 자세 및 얼굴의 털을 비롯한 얼굴 특징

얼굴 감지 cURL 요청 예제

노트

REST 호출 시 반드시 구독 키를 발급받은 위치와 동일한 위치의 주소를 사용해야 합니다. 가령 westus 지역에서 구독 키를 발급받았다면, 아래 예제 코드의 URL에서 "westcentralus"를 "westus"로 변경해야 합니다.

@@ECHO OFF

curl -v -X POST "https://westcentralus.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&returnFaceAttributes={string}"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"
역주

본문의 모든 cURL 예제는 명령줄에 한 줄로 입력해야 하며, --data-ascii 줄도 마찬가지입니다. 본문의 예제들은 cURL 명령어가 너무 길기 때문에 가독성을 위해서 정리된 것입니다. 또한 @@ECHO OFF 명령은 그냥 무시하는 것을 권해드립니다. 그리고 --data-ascii 줄의 "{body}" 부분에는 "{'url':'http://<image url>'}"과 같이 감지 대상 이미지의 경로를 JSON 형식으로 지정하면 됩니다. 가령 이번 예제의 경우, returnFaceAttributes 쿼리 매개 변수에 age,gender를 지정한다고 가정할 때 다음과 같이 입력하게 됩니다. 또한, 구독 키를 헤더에 지정해서 전달하는 방법에 유의하시기 바랍니다.

curl -v -X POST "https://eastasia.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&returnFaceAttributes=age,gender" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: <subscription key>" --data-ascii "{'url':'<image url>'}"

얼굴 감지 결과 응답 살펴보기

정상적으로 처리된 응답은 JSON 형식으로 반환됩니다. 다음은 성공한 응답의 사례입니다:

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "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.0,
        "y": 80.1 
      },
      "eyeLeftInner": {
        "x": 418.9,
        "y": 78.0 
      },
      "eyebrowRightInner": {
        "x": 4.8,
        "y": 69.7 
      },
      "eyebrowRightOuter": {
        "x": 5.5,
        "y": 68.5 
      },
      "eyeRightInner": {
        "x": 441.5,
        "y": 75.0 
      },
      "eyeRightTop": {
        "x": 446.4,
        "y": 71.7 
      },
      "eyeRightBottom": {
        "x": 447.0,
        "y": 75.3 
      },
      "eyeRightOuter": {
        "x": 451.7,
        "y": 73.4 
      },
      "noseRootLeft": {
        "x": 428.0,
        "y": 77.1 
      },
      "noseRootRight": {
        "x": 435.8,
        "y": 75.6 
      },
      "noseLeftAlarTop": {
        "x": 428.3,
        "y": 89.7 
      },
      "noseRightAlarTop": {
        "x": 442.2,
        "y": 87.0 
      },
      "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": {
      "age": 71.0,
      "gender": "male",
      "smile": 0.88,
      "facialHair": {
        "mustache": 0.8,
        "beard": 0.1,
        "sideburns": 0.02
      },
      "glasses": "sunglasses",
      "headPose": {
        "roll": 2.1,
        "yaw": 3,
        "pitch": 0
      }
    }
  }
]

cURL을 이용해서 Face API로 이미지의 얼굴 식별하기

Face - Identify 메서드를 이용해서, 미리 생성해야하고 이후 편집이 가능한 인물 데이터베이스 (인물 그룹으로 정의된) 및 감지된 얼굴에 기반해서 인물을 식별합니다.

얼굴 식별 cURL 요청 예제

노트

REST 호출 시 반드시 구독 키를 발급받은 위치와 동일한 위치의 주소를 사용해야 합니다. 가령 westus 지역에서 구독 키를 발급받았다면, 아래 예제 코드의 URL에서 "westcentralus"를 "westus"로 변경해야 합니다.

@@ECHO OFF

curl -v -X POST "https://westcentralus.api.cognitive.microsoft.com/face/v1.0/identify"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"
역주

얼굴 식별의 경우, --data-ascii 줄의 "{body}" 부분에 전달해야 하는 정보가 조금 복잡합니다. 다음은 API 참조 문서에서 발췌한 예제입니다.

{    
  "personGroupId": "sample_group",
  "faceIds": [
    "c5c24a82-6845-4031-9d5d-978df9175426",
    "65d083d4-9447-47d1-af30-b626144bf0fb"
  ],
  "maxNumOfCandidatesReturned": 1,
  "confidenceThreshold": 0.5
}

얼굴 식별 결과 응답 살펴보기

정상적으로 처리된 응답은 JSON 형식으로 반환됩니다. 다음은 성공한 응답의 사례입니다:

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "candidates": [
      {
        "personId": "25985303-c537-4467-b41d-bdb45cd95ca1",
        "confidence": 0.92
      }
    ]
  },
  {
    "faceId": "65d083d4-9447-47d1-af30-b626144bf0fb",
    "candidates": [
      {
        "personId": "2ae4935b-9659-44c3-977f-61fac20d0538",
        "confidence": 0.89
      }
    ]
  }
]