> ## 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.
# Specifiche di integrazione dell'API di localizzazione dei tratti del viso
> Face Transformation 集成指南 - XHuoAPI
Questo documento presenterà una specifica di integrazione dell'API di localizzazione dei tratti del viso, che può localizzare i tratti del viso (noto anche come localizzazione dei punti chiave del viso) tramite l'input di un'immagine, calcolando 90 punti che compongono il contorno del viso, inclusi sopracciglia (8 punti a sinistra e 8 a destra), occhi (8 punti a sinistra e 8 a destra), naso (13 punti), bocca (22 punti), contorno del viso (21 punti), pupille (2 punti).
## Processo di richiesta
Per utilizzare l'API, è necessario prima andare alla pagina corrispondente dell'[API di localizzazione dei tratti del viso](https://api.xhuoapi.ai/documents/20945baf-b263-457b-be5f-0332c2180a57) per richiedere il servizio corrispondente. Una volta entrati nella pagina, fare clic sul pulsante "Acquire", come mostrato nell'immagine:
Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login che invita a registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si tornerà automaticamente alla pagina corrente.
Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente questa API.
## Utilizzo di base
Innanzitutto, è importante comprendere il modo di utilizzo di base, ovvero inserire il link dell'immagine per ottenere l'immagine risultante elaborata. È necessario semplicemente trasmettere un campo `image_url`, l'immagine del viso è mostrata qui sotto:
Possiamo quindi compilare i contenuti corrispondenti nell'interfaccia, come mostrato nell'immagine:
Si può notare che qui abbiamo impostato le intestazioni della richiesta, inclusi:
* `accept`: il formato della risposta desiderata, qui impostato su `application/json`, ovvero formato JSON.
* `authorization`: la chiave per chiamare l'API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, sono state impostate le informazioni del corpo della richiesta, inclusi:
* `image_url`: il link all'immagine del viso da elaborare.
* `mode`: modalità di rilevamento. 0 per rilevare tutti i volti presenti, 1 per rilevare il volto di area massima. Il valore predefinito è 0.
* `face_model_version`: versione del modello algoritmico utilizzato per il servizio di riconoscimento facciale, il valore predefinito è `3.0`.
* `need_rotate_detection`: se abilitare il supporto per il riconoscimento della rotazione dell'immagine. 0 per disabilitare, 1 per abilitare. Il valore predefinito è 0.
Dopo aver effettuato le scelte, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell'immagine:
Cliccando sul pulsante "Try" è possibile effettuare un test, come mostrato nell'immagine sopra, e qui abbiamo ottenuto il seguente risultato:
```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
}
]
}
]
}
```
Possiamo vedere che in questo momento abbiamo ottenuto le informazioni relative al volto della persona nell'immagine, inclusi i dettagli sulla posizione delle caratteristiche facciali (punti chiave del volto), la versione del modello di algoritmo utilizzato per il riconoscimento facciale e altro ancora.
La descrizione dei campi è la seguente:
* `image_width` ：larghezza dell'immagine richiesta.
* `image_height` ：altezza dell'immagine richiesta.
* `face_model_version`：versione del modello algoritmico utilizzato per il riconoscimento facciale.
* `face_shape_set`：informazioni specifiche sulla localizzazione dei tratti del viso (punti chiave del viso).
* `face_profile` ：21 punti che descrivono il profilo del viso.
* `x` ：coordinata x
* `y` ：coordinata y
* `left_eye` ：8 punti che descrivono il profilo dell'occhio sinistro.
* `x` ：coordinata x
* `y` ：coordinata y
* `right_eye ` ：8 punti che descrivono il profilo dell'occhio destro.
* `x` ：coordinata x
* `y` ：coordinata y
* `left_eye_brow` ：8 punti che descrivono il profilo dell'arcata sopracciliare sinistra.
* `x` ：coordinata x
* `y` ：coordinata y
* `right_eye_brow ` ：8 punti che descrivono il profilo dell'arcata sopracciliare destra.
* `x` ：coordinata x
* `y` ：coordinata y
* `mouth` ：22 punti che descrivono il profilo della bocca.
* `x` ：coordinata x
* `y` ：coordinata y
* `nose` ：13 punti che descrivono il profilo del naso.
* `x` ：coordinata x
* `y` ：coordinata y
* `left_pupil` ：1 punto che descrive il profilo della pupilla sinistra.
* `x` ：coordinata x
* `y` ：coordinata y
* `right_pupil` ：1 punto che descrive il profilo della pupilla destra.
* `x` ：coordinata x
* `y` ：coordinata y
Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:
```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"
}'
```
Il codice di integrazione in Python è il seguente:
```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)
```
## Gestione degli errori
Quando si chiama l'API, se si verifica un errore, l'API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
* `400 token_mismatched`：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
* `400 api_not_implemented`：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
* `401 invalid_token`：Non autorizzato, token di autorizzazione non valido o mancante.
* `429 too_many_requests`：Troppe richieste, hai superato il limite di frequenza.
* `500 api_error`：Errore interno del server, qualcosa è andato storto sul server.
### Esempio di risposta di errore
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusione
Attraverso questo documento, hai appreso come utilizzare l'API di localizzazione dei tratti del viso per analizzare l'immagine fornita. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.