> ## 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 Veo Tasks

> Veo Video Generation 集成指南 - XHuoAPI

La principale funzionalità dell'API Veo Tasks è quella di interrogare lo stato di esecuzione di un'attività utilizzando l'ID dell'attività generato dall'API Veo Videos Generation.

Questo documento fornirà una guida dettagliata per l'integrazione dell'API Veo Tasks, aiutandoti a integrare facilmente e sfruttare appieno le potenti funzionalità di questa API. Con l'API Veo Tasks, puoi facilmente interrogare lo stato di esecuzione delle attività dell'API Veo Videos Generation.

## Processo di richiesta

Per utilizzare l'API Veo Tasks, è necessario prima andare alla pagina di richiesta [API Veo Videos Generation](https://api.xhuoapi.ai/documents/63e01dc3-eb21-499e-8049-3025c460058f) per richiedere il servizio corrispondente, quindi copiare l'ID dell'attività dell'API Veo Videos Generation, come mostrato nell'immagine:

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

Infine, accedi alla pagina dell'API Tasks [API Veo Tasks](https://api.xhuoapi.ai/documents/52778f8b-93ce-4db3-a62c-bcf0a92e5f3c) 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 questa API.

## Esempio di richiesta

L'API Veo Tasks può essere utilizzata per interrogare i risultati dell'API Veo Videos Generation. Per informazioni su come utilizzare l'API Veo Videos Generation, fare riferimento al documento [API Veo Videos Generation](https://api.xhuoapi.ai/documents/63e01dc3-eb21-499e-8049-3025c460058f).

Prendiamo come esempio un ID di attività restituito dal servizio API Veo Videos Generation e dimostriamo come utilizzare questa API. Supponiamo di avere un ID di attività: 1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed, e ora dimostriamo come passare un ID di attività.

### Esempio di attività

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

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

**Request Headers** includono:

* `accept`: specifica di ricevere la risposta in formato JSON, qui si compila con `application/json`.
* `authorization`: la chiave per chiamare l'API, che può essere selezionata direttamente dopo la richiesta.

**Request Body** include:

* `id`: l'ID dell'attività caricata.
* `action`: il modo in cui operare sull'attività.

Impostato come mostrato nell'immagine seguente:

<p>
  <img src="https://cdn.xhuoapi.ai/xztiqi.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/bsqh3i.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/veo/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "action": "retrieve"
}'
```

#### Python

```python theme={null}
import requests

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

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

payload = {
    "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
    "action": "retrieve"
}

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

### Esempio di risposta

Se la richiesta ha successo, l'API restituirà i dettagli di questa attività video. Ad esempio:

```json theme={null}
{
  "_id": "68834c16550a4144a5112589",
  "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46",
  "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2",
  "created_at": 1753435158.509,
  "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae",
  "request": {
    "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc",
    "action": "text2video",
    "model": "veo2",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
  },
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "type": "videos",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
    "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
    "data": [
      {
        "id": "2f43ceed37944b4d836e1a1899dad0a1",
        "video_url": "https://platform.cdn.xhuoapi.ai/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
        "created_at": "2025-07-25 17:19:20",
        "complete_at": "2025-07-25 17:21:45",
        "state": "succeeded"
      }
    ]
  }
}
```

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

* `id`, l'ID che genera questa attività video, utilizzato per identificare univocamente questa attività di generazione video.
* `request`, informazioni sulla richiesta nell'attività video.
* `response`, informazioni sulla risposta nell'attività video.

## Operazione di query in batch

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

**Request Body** include:

* `ids`: array degli ID delle attività caricate.
* `action`: il modo in cui operare sull'attività.

Impostato come mostrato nell'immagine seguente:

<p>
  <img src="https://cdn.xhuoapi.ai/4p5uvq.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/g3b7g6.png" width="500" className="m-auto" />
</p>

Alcuni esempi di codice sono i seguenti:

### Esempio di risposta

Se la richiesta ha successo, l'API restituirà i dettagli specifici di tutte le attività video in batch. Ad esempio:

```json theme={null}
{
  "items": [
    {
      "_id": "68834c16550a4144a5112589",
      "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
      "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46",
      "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2",
      "created_at": 1753435158.509,
      "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae",
      "request": {
        "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc",
        "action": "text2video",
        "model": "veo2",
        "prompt": "Tazza da caffè in ceramica bianca su un piano in marmo lucido con luce mattutina dalla finestra. La fotocamera ruota lentamente di 360 gradi attorno alla tazza, fermandosi brevemente sul manico."
      },
      "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
        "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
        "data": [
          {
            "id": "2f43ceed37944b4d836e1a1899dad0a1",
            "video_url": "https://platform.cdn.xhuoapi.ai/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
            "created_at": "2025-07-25 17:19:20",
            "complete_at": "2025-07-25 17:21:45",
            "state": "succeeded"
          }
        ]
      }
    },
    {
      "_id": "68834c16550a4144a5112589",
      "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
      "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46",
      "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2",
      "created_at": 1753435158.509,
      "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae",
      "request": {
        "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc",
        "action": "text2video",
        "model": "veo2",
        "prompt": "Tazza da caffè in ceramica bianca su un piano in marmo lucido con luce mattutina dalla finestra. La fotocamera ruota lentamente di 360 gradi attorno alla tazza, fermandosi brevemente sul manico."
      },
      "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
        "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
        "data": [
          {
            "id": "2f43ceed37944b4d836e1a1899dad0a1",
            "video_url": "https://platform.cdn.xhuoapi.ai/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
            "created_at": "2025-07-25 17:19:20",
            "complete_at": "2025-07-25 17:21:45",
            "state": "succeeded"
          }
        ]
      }
    }
  ],
  "count": 2
}
```

Restituisce risultati con diversi campi, dove items contiene i dettagli specifici dei compiti video in batch, ogni informazione specifica del video compito è la stessa dei risultati di una singola richiesta sopra.

* `items`, tutti i dettagli specifici dei compiti video in batch. È un array, ogni elemento dell'array ha lo stesso formato del risultato della richiesta di un singolo compito.
* `count`, il numero di compiti video in batch richiesti.

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/veo/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"],
  "action": "retrieve_batch"
}'
```

## 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 compreso come utilizzare l'API Veo Tasks per interrogare i dettagli specifici di compiti video singoli o in batch. 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.