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

# Integrazione e utilizzo dell'API Task per foto identificative AI

> AI ID Photo Production 集成指南 - XHuoAPI

La principale funzionalità dell'API Task per foto identificative AI è quella di consultare lo stato di esecuzione di un'attività generata dall'API di creazione di foto identificative AI, inserendo l'ID dell'attività.

Questo documento fornirà una descrizione dettagliata dell'integrazione dell'API Task per foto identificative AI, aiutandoti a integrare facilmente e sfruttare appieno le potenti funzionalità di quest'API. Con l'API Task per foto identificative AI, puoi facilmente controllare lo stato di esecuzione delle attività dell'API di creazione di foto identificative AI.

## Processo di richiesta

Per utilizzare l'API Task per foto identificative AI, è necessario prima andare alla pagina di richiesta [API di creazione di foto identificative AI](https://api.xhuoapi.ai/documents/bf7214a3-8447-4157-8a75-f5bb39d5ed1b) per richiedere il servizio corrispondente, quindi copiare l'ID dell'attività dell'API di creazione di foto identificative AI, come mostrato nell'immagine:

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

Infine, accedi alla pagina dell'API Tasks [API Task per foto identificative AI](https://api.xhuoapi.ai/documents/3a23ee34-8689-406b-9042-7954224348ad) per richiedere il servizio corrispondente. Una volta entrato nella pagina, fai clic sul pulsante "Acquire", come mostrato nell'immagine:

![Pagina di richiesta](https://cdn.xhuoapi.ai/rci31i.png)

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla [pagina di login](https://api.xhuoapi.ai) che ti invita a registrarti e accedere. Dopo aver effettuato il login o la registrazione, verrai automaticamente riportato alla pagina corrente.

Alla prima richiesta, verrà offerto un credito gratuito, che ti consente di utilizzare gratuitamente quest'API.

## Esempio di richiesta

L'API Task per foto identificative AI può essere utilizzata per consultare i risultati dell'API di creazione di foto identificative AI. Per informazioni su come utilizzare l'API di creazione di foto identificative AI, fare riferimento al documento [API di creazione di foto identificative AI](https://api.xhuoapi.ai/documents/d6ea75a4-836e-490a-aee5-7ca911a808fd).

Prendiamo come esempio un ID di attività restituito dal servizio API di creazione di foto identificative AI e dimostriamo come utilizzare quest'API. Supponiamo di avere un ID di attività: `16f96e95-d95c-46ef-b183-139b9bd1aebd`, e ora dimostriamo come passare un ID di attività.

### Esempio di attività

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

### Impostazione dell'intestazione della richiesta e del corpo della richiesta

**Intestazioni della richiesta** includono:

* `accept`: specifica di ricevere la risposta in formato JSON, qui inserito come `application/json`.
* `authorization`: chiave per chiamare l'API, selezionabile direttamente dopo la richiesta.

**Corpo della richiesta** include:

* `id`: ID dell'attività caricata.
* `action`: modalità di operazione sull'attività.

Impostato come mostrato nell'immagine:

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

### Esempio di codice

Si può notare che, sul lato destro della pagina, sono già stati generati automaticamente vari codici in diverse lingue, come mostrato nell'immagine:

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

Alcuni esempi di codice sono i seguenti:

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "action": "retrieve"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/headshots/tasks"

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

payload = {
    "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "action": "retrieve"
}

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

### Esempio di risposta

Dopo una richiesta riuscita, l'API restituirà i dettagli di questa attività di foto identificativa. Ad esempio:

```json theme={null}
{
  "_id": "67276ab6550a4144a53b6036",
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
  "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
  "created_at": 1730636470.402,
  "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
  "request": {
    "mode": "relax",
    "template": "male_portrait",
    "image_urls": [
      "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
    ],
    "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
  },
  "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "data": [
      {
        "id": "202411032022077381",
        "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      },
      {
        "id": "202411032022079194",
        "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      }
    ]
  }
}
```

Il risultato restituito contiene diversi campi, il campo request è il corpo della richiesta inviato per avviare l'attività, mentre il campo response è il corpo della risposta restituito al termine dell'attività. La descrizione dei campi è la seguente.

* `id`, ID dell'attività di foto identificativa generata, utilizzato per identificare univocamente questa attività di generazione di foto identificativa.
* `request`, informazioni sulla richiesta nell'attività di foto identificativa.
* `response`, informazioni sulla risposta nell'attività di foto identificativa.

## Operazione di query in batch

Questa è per consultare i dettagli delle attività di foto identificativa per più ID di attività, a differenza di quanto sopra, è necessario selezionare l'azione come retrieve\_batch.

**Corpo della richiesta** include:

* `ids`: array degli ID delle attività caricate.
* `action`: modalità di operazione sull'attività.

Impostato come mostrato nell'immagine:

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

### Esempio di codice

Si può notare che, sul lato destro della pagina, sono già stati generati automaticamente vari codici in diverse lingue, come mostrato nell'immagine:

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

Alcuni esempi di codice sono i seguenti:

### Esempio di risposta

Dopo una richiesta riuscita, l'API restituirà i dettagli specifici di tutte le attività di foto identificativa in batch. Ad esempio:

```json theme={null}
{
  "items": [
    {
      "_id": "67276ab6550a4144a53b6036",
      "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636470.402,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relax",
        "template": "ritratto_maschile",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
        "data": [
          {
            "id": "202411032022077381",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男形象照"
          },
          {
            "id": "202411032022079194",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男形象照"
          }
        ]
      }
    },
    {
      "_id": "67276c52550a4144a53b995b",
      "id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636882.359,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relax",
        "template": "ritratto_maschile",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "50b2b4a8-6c1c-4b95-ac0b-46e5b97c7b18",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
        "status": "sconosciuto",
        "data": []
      }
    }
  ],
  "count": 2
}
```

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
  "action": "retrieve_batch"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/headshots/tasks"

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

payload = {
    "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
    "action": "retrieve_batch"
}

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

## Gestione degli errori

In caso di errore durante la chiamata all'API, 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 compreso come utilizzare l'API Task per le foto di identificazione AI per interrogare i dettagli di singoli o batch di compiti per foto di identificazione. 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.