> ## 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 对接说明，它可以通过输入图片，对请求图片进行五官定位（也称人脸关键点定位），计算构成人脸轮廓的 90 个点，包括眉毛（左右各 8 点）、眼睛（左右各 8 点）、鼻子（13 点）、嘴巴（22 点）、脸型轮廓（21 点）、眼珠\[或瞳孔]（2点）。
## 申请流程
要使用 API，需要先到 [五官定位 API](https://api.xhuoapi.ai/documents/20945baf-b263-457b-be5f-0332c2180a57) 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：
如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。
在首次申请时会有免费额度赠送，可以免费使用该 API。
## 基本使用
首先先了解下基本的使用方式，就是输入图片链接，便可获得处理后结果图片，首先需要简单地传递一个 `image_url` 字段，人脸图片如下图所示：
我们接下来就可以在界面上填写对应的内容，如图所示：
可以看到这里我们设置了 Request Headers，包括：
* `accept`：想要接收怎样格式的响应结果，这里填写为 `application/json`，即 JSON 格式。
* `authorization`：调用 API 的密钥，申请之后可以直接下拉选择。
另外设置了 Request Body，包括：
* `image_url`：需要处理的人脸图片链接。
* `mode`：检测模式。0 为检测所有出现的人脸， 1 为检测面积最大的人脸。默认为 0。
* `face_model_version`：人脸识别服务所用的算法模型版本，默认是`3.0` 。
* `need_rotate_detection`：是否开启图片旋转识别支持。0为不开启，1为开启。默认为0。
选择之后，可以发现右侧也生成了对应代码，如图所示：
点击「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`：Bad request, possibly due to missing or invalid parameters.
* `400 api_not_implemented`：Bad request, possibly due to missing or invalid parameters.
* `401 invalid_token`：Unauthorized, invalid or missing authorization token.
* `429 too_many_requests`：Too many requests, you have exceeded the rate limit.
* `500 api_error`：Internal server error, something went wrong on the server.
### 错误响应示例
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 结论
通过本文档，您已经了解了如何使用 五官定位 API 对输入的图片进行五官定位。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。