> ## 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.

# Istruzioni per l'integrazione dell'API di animazione dei ritratti

> Face Transformation 集成指南 - XHuoAPI

Questo documento introduce un'API di animazione dei ritratti che può generare immagini anime personalizzate a partire da una foto del volto, utilizzabile per creare avatar personalizzati, attività divertenti, applicazioni di effetti speciali e altri scenari, migliorando l'esperienza di intrattenimento sociale.

## Processo di richiesta

Per utilizzare l'API, è necessario prima andare alla pagina corrispondente dell'[API di animazione dei ritratti](https://api.xhuoapi.ai/documents/6b6313f1-f398-4d29-933d-5a652cfa1c37) per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare sul pulsante "Acquire", come mostrato nell'immagine:

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

Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per 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 l'API senza costi.

## 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 volto è mostrata qui sotto:

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

Possiamo quindi compilare il contenuto corrispondente nell'interfaccia, come mostrato nell'immagine:

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

Si può notare che qui abbiamo impostato le intestazioni della richiesta, tra cui:

* `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, abbiamo impostato il corpo della richiesta, che include:

* `image_url`: il link all'immagine del volto da elaborare.

Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell'immagine:

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

Cliccando sul pulsante "Try" è possibile effettuare un test, come mostrato nell'immagine sopra, e qui abbiamo ottenuto il seguente risultato:

```json theme={null}
{
  "image_url": "https://faceeffect-1254418846.cos.ap-guangzhou.myqcloud.com/ft/FaceCartoonPic/1256437459/8567833b-7831-406c-9ff5-890e5f7e020e"
}
```

Si può notare che nel risultato restituito c'è un campo `image_url`, che è l'immagine del volto cartone modificata. Le informazioni sul volto modificate sono mostrate qui sotto:

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

Si può vedere che il volto nell'immagine ha già generato un'immagine anime personalizzata.

Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è il seguente:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/face/cartoon' \
-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/cartoon"

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 animazione dei ritratti per generare immagini anime personalizzate a partire dalle immagini fornite. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio l'API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.