> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 오관 위치 API 연동 설명

> Face Transformation 集成指南 - XHuoAPI

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

## 신청 절차

API를 사용하려면 먼저 [오관 위치 API](https://api.xhuoapi.ai/documents/20945baf-b263-457b-be5f-0332c2180a57) 해당 페이지에서 서비스를 신청해야 합니다. 페이지에 들어가면 "Acquire" 버튼을 클릭합니다. 아래 그림과 같이:

![](https://cdn.xhuoapi.ai/q6ytrc.png)

로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 등록 및 로그인을 요청합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다.

첫 신청 시 무료 한도가 제공되어 해당 API를 무료로 사용할 수 있습니다.

## 기본 사용

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

<p>
  <img src="https://cdn.xhuoapi.ai/lrbtcn.jpg" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.xhuoapi.ai/y3g837.png" width="500" className="m-auto" />
</p>

여기서 요청 헤더를 설정한 것을 볼 수 있습니다. 포함된 내용은 다음과 같습니다:

* `accept`: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 `application/json` 즉 JSON 형식으로 입력합니다.
* `authorization`: API 호출에 필요한 키로, 신청 후 바로 드롭다운에서 선택할 수 있습니다.

또한 요청 본체를 설정했습니다. 포함된 내용은 다음과 같습니다:

* `image_url`: 처리할 얼굴 이미지 링크입니다.
* `mode`: 감지 모드. 0은 모든 얼굴을 감지하고, 1은 면적이 가장 큰 얼굴을 감지합니다. 기본값은 0입니다.
* `face_model_version`: 얼굴 인식 서비스에서 사용하는 알고리즘 모델 버전으로, 기본값은 `3.0`입니다.
* `need_rotate_detection`: 이미지 회전 인식 지원 여부입니다. 0은 비활성화, 1은 활성화입니다. 기본값은 0입니다.

선택 후, 오른쪽에도 해당 코드가 생성된 것을 확인할 수 있습니다. 아래 그림과 같이:

<p>
  <img src="https://cdn.xhuoapi.ai/2ceul8.png" width="500" className="m-auto" />
</p>

"Try" 버튼을 클릭하면 테스트를 진행할 수 있습니다. 위 그림과 같이, 여기서 다음과 같은 결과를 얻었습니다:

```json theme={null}
{
  "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의 코드는 다음과 같습니다:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/face/analyze' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.xhuoapi.ai/lrbtcn.jpg"
}'
```

Python의 연동 코드는 다음과 같습니다:

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/face/analyze"

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

payload = {
    "image_url": "https://cdn.xhuoapi.ai/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`：내부 서버 오류, 서버에서 문제가 발생했습니다.

### 오류 응답 예시

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

## 결론

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