메인 콘텐츠로 건너뛰기
본 문서에서는 오관 위치 API 연동 설명을 소개합니다. 이 API는 입력된 이미지를 통해 요청된 이미지의 오관 위치(또는 얼굴 주요 점 위치)를 수행하며, 얼굴 윤곽을 구성하는 90개의 점을 계산합니다. 여기에는 눈썹(좌우 각각 8점), 눈(좌우 각각 8점), 코(13점), 입(22점), 얼굴형 윤곽(21점), 눈동자또는 동공이 포함됩니다.

​
신청 절차

API를 사용하려면 먼저 오관 위치 API 해당 페이지에서 서비스를 신청해야 합니다. 페이지에 들어가면 “Acquire” 버튼을 클릭합니다. 아래 그림과 같이: 로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 등록 및 로그인을 요청합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다. 첫 신청 시 무료 한도가 제공되어 해당 API를 무료로 사용할 수 있습니다.

​
기본 사용

먼저 기본 사용 방식을 이해해야 합니다. 즉, 이미지 링크를 입력하면 처리된 결과 이미지를 얻을 수 있습니다. 먼저 간단하게 image_url 필드를 전달해야 합니다. 얼굴 이미지는 아래 그림과 같습니다:

이제 화면에 해당 내용을 입력할 수 있습니다. 아래 그림과 같이:

여기서 요청 헤더를 설정한 것을 볼 수 있습니다. 포함된 내용은 다음과 같습니다:
  • accept: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 application/json 즉 JSON 형식으로 입력합니다.
  • authorization: API 호출에 필요한 키로, 신청 후 바로 드롭다운에서 선택할 수 있습니다.
또한 요청 본체를 설정했습니다. 포함된 내용은 다음과 같습니다:
  • image_url: 처리할 얼굴 이미지 링크입니다.
  • mode: 감지 모드. 0은 모든 얼굴을 감지하고, 1은 면적이 가장 큰 얼굴을 감지합니다. 기본값은 0입니다.
  • face_model_version: 얼굴 인식 서비스에서 사용하는 알고리즘 모델 버전으로, 기본값은 3.0입니다.
  • need_rotate_detection: 이미지 회전 인식 지원 여부입니다. 0은 비활성화, 1은 활성화입니다. 기본값은 0입니다.
선택 후, 오른쪽에도 해당 코드가 생성된 것을 확인할 수 있습니다. 아래 그림과 같이:

“Try” 버튼을 클릭하면 테스트를 진행할 수 있습니다. 위 그림과 같이, 여기서 다음과 같은 결과를 얻었습니다: 
{
  "image_width": 690,
  "image_height": 920,
  "face_model_version": "3.0",
  "face_shape_set": [
    {
      "face_profile": [
        {
          "x": 294,
          "y": 207
        },
        {
          "x": 289,
          "y": 216
        },
        {
          "x": 286,
          "y": 226
        },
        {
          "x": 284,
          "y": 236
        },
        {
          "x": 283,
          "y": 246
        },
        {
          "x": 283,
          "y": 256
        },
        {
          "x": 284,
          "y": 266
        },
        {
          "x": 286,
          "y": 276
        },
        {
          "x": 289,
          "y": 285
        },
        {
          "x": 294,
          "y": 294
        },
        {
          "x": 301,
          "y": 301
        },
        {
          "x": 314,
          "y": 306
        },
        {
          "x": 327,
          "y": 307
        },
        {
          "x": 340,
          "y": 306
        },
        {
          "x": 353,
          "y": 302
        },
        {
          "x": 365,
          "y": 296
        },
        {
          "x": 374,
          "y": 287
        },
        {
          "x": 382,
          "y": 276
        },
        {
          "x": 387,
          "y": 264
        },
        {
          "x": 392,
          "y": 251
        },
        {
          "x": 396,
          "y": 238
        }
      ],
      "left_eye": [
        {
          "x": 298,
          "y": 208
        },
        {
          "x": 301,
          "y": 212
        },
        {
          "x": 305,
          "y": 214
        },
        {
          "x": 309,
          "y": 215
        },
        {
          "x": 314,
          "y": 216
        },
        {
          "x": 313,
          "y": 210
        },
        {
          "x": 309,
          "y": 207
        },
        {
          "x": 303,
          "y": 206
        }
      ],
      "right_eye": [
        {
          "x": 363,
          "y": 229
        },
        {
          "x": 358,
          "y": 230
        },
        {
          "x": 353,
          "y": 229
        },
        {
          "x": 347,
          "y": 227
        },
        {
          "x": 342,
          "y": 224
        },
        {
          "x": 348,
          "y": 221
        },
        {
          "x": 354,
          "y": 221
        },
        {
          "x": 360,
          "y": 223
        }
      ],
      "left_eye_brow": [
        {
          "x": 296,
          "y": 196
        },
        {
          "x": 302,
          "y": 197
        },
        {
          "x": 308,
          "y": 198
        },
        {
          "x": 313,
          "y": 200
        },
        {
          "x": 319,
          "y": 202
        },
        {
          "x": 315,
          "y": 195
        },
        {
          "x": 309,
          "y": 192
        },
        {
          "x": 302,
          "y": 192
        }
      ],
      "right_eye_brow": [
        {
          "x": 377,
          "y": 221
        },
        {
          "x": 369,
          "y": 217
        },
        {
          "x": 360,
          "y": 213
        },
        {
          "x": 350,
          "y": 211
        },
        {
          "x": 341,
          "y": 208
        },
        {
          "x": 351,
          "y": 204
        },
        {
          "x": 362,
          "y": 206
        },
        {
          "x": 372,
          "y": 211
        }
      ],
      "mouth": [
        {
          "x": 296,
          "y": 262
        },
        {
          "x": 297,
          "y": 269
        },
        {
          "x": 299,
          "y": 276
        },
        {
          "x": 305,
          "y": 281
        },
        {
          "x": 315,
          "y": 283
        },
        {
          "x": 326,
          "y": 282
        },
        {
          "x": 335,
          "y": 277
        },
        {
          "x": 325,
          "y": 269
        },
        {
          "x": 315,
          "y": 262
        },
        {
          "x": 309,
          "y": 261
        },
        {
          "x": 305,
          "y": 258
        },
        {
          "x": 300,
          "y": 259
        },
        {
          "x": 299,
          "y": 265
        },
        {
          "x": 303,
          "y": 269
        },
        {
          "x": 307,
          "y": 272
        },
        {
          "x": 316,
          "y": 275
        },
        {
          "x": 325,
          "y": 276
        },
        {
          "x": 326,
          "y": 272
        },
        {
          "x": 317,
          "y": 269
        },
        {
          "x": 308,
          "y": 265
        },
        {
          "x": 304,
          "y": 263
        },
        {
          "x": 300,
          "y": 262
        }
      ],
      "nose": [
        {
          "x": 311,
          "y": 242
        },
        {
          "x": 325,
          "y": 220
        },
        {
          "x": 319,
          "y": 226
        },
        {
          "x": 313,
          "y": 231
        },
        {
          "x": 307,
          "y": 236
        },
        {
          "x": 302,
          "y": 243
        },
        {
          "x": 306,
          "y": 249
        },
        {
          "x": 311,
          "y": 252
        },
        {
          "x": 318,
          "y": 254
        },
        {
          "x": 329,
          "y": 253
        },
        {
          "x": 327,
          "y": 243
        },
        {
          "x": 326,
          "y": 235
        },
        {
          "x": 326,
          "y": 228
        }
      ],
      "left_pupil": [
        {
          "x": 310,
          "y": 211
        }
      ],
      "right_pupil": [
        {
          "x": 357,
          "y": 225
        }
      ]
    }
  ]
}
우리는 이때 이미지에서 사람 얼굴의 관련 정보를 얻었으며, 여기에는 오관 위치(얼굴 키포인트) 구체적인 정보와 얼굴 인식에 사용된 알고리즘 모델 버전 등이 포함됩니다. 필드 설명은 다음과 같습니다:
  • image_width ：요청한 이미지 너비.
  • image_height ：요청한 이미지 높이.
  • face_model_version：얼굴 인식에 사용되는 알고리즘 모델 버전.
  • face_shape_set：오관 위치(얼굴 주요 점) 구체 정보.
    • face_profile ：얼굴형 윤곽을 설명하는 21 점.
      • x ：x좌표
      • y ：y좌표
    • left_eye ：왼쪽 눈 윤곽을 설명하는 8 점.
      • x ：x좌표
      • y ：y좌표
    • right_eye ：오른쪽 눈 윤곽을 설명하는 8 점.
      • x ：x좌표
      • y ：y좌표
    • left_eye_brow ：왼쪽 눈썹 윤곽을 설명하는 8 점.
      • x ：x좌표
      • y ：y좌표
    • right_eye_brow ：오른쪽 눈썹 윤곽을 설명하는 8 점.
      • x ：x좌표
      • y ：y좌표
    • mouth ：입 윤곽을 설명하는 22 점.
      • x ：x좌표
      • y ：y좌표
    • nose ：코 윤곽을 설명하는 13 점.
      • x ：x좌표
      • y ：y좌표
    • left_pupil ：왼쪽 동공 윤곽의 1 점.
      • x ：x좌표
      • y ：y좌표
    • right_pupil ：오른쪽 동공 윤곽의 1 점.
      • x ：x좌표
      • y ：y좌표
또한, 해당하는 연동 코드를 생성하고 싶다면, 생성된 코드를 직접 복사할 수 있습니다. 예를 들어 CURL의 코드는 다음과 같습니다: 
curl -X POST 'https://api.acedata.cloud/face/analyze' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}'
Python의 연동 코드는 다음과 같습니다: 
import requests

url = "https://api.acedata.cloud/face/analyze"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
오류 처리

API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:
  • 400 token_mismatched：잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다.
  • 400 api_not_implemented：잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다.
  • 401 invalid_token：권한 없음, 잘못되었거나 누락된 인증 토큰.
  • 429 too_many_requests：요청이 너무 많음, 비율 제한을 초과했습니다.
  • 500 api_error：내부 서버 오류, 서버에서 문제가 발생했습니다.

​
오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
결론

이 문서를 통해, 오관 위치 API를 사용하여 입력된 이미지에 대해 오관 위치를 수행하는 방법을 이해하셨습니다. 이 문서가 해당 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주시기 바랍니다.