> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Dreamina Tasks

> Dreamina API guide - Ace Data Cloud

## Integrazione e utilizzo dell'API Dreamina Tasks

L'API Dreamina Tasks è utilizzata per interrogare i risultati dell'esecuzione dei compiti video digitali creati dall'[API di generazione video Dreamina](https://platform.acedata.cloud/documents/dreamina-videos-integration). Quando si passa `callback_url` o `async: true` nell'interfaccia di generazione, l'interfaccia restituirà immediatamente un `task_id`, che puoi utilizzare per interrogare lo stato del compito e l'indirizzo video finale tramite questa interfaccia utilizzando `task_id` o `trace_id`. **Questa interfaccia è gratuita.**

## Processo di richiesta

Per utilizzare le API della serie Dreamina, prima vai al [Pannello di controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro.

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e a effettuare il login; una volta completato, verrai automaticamente riportato alla pagina corrente.

**Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio.** La prima richiesta ti darà un credito gratuito, per un'esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel [pannello di controllo](https://platform.acedata.cloud/console/coin).

## Parametri di richiesta

**Request Headers**

* `accept`: specifica di ricevere la risposta in formato JSON, inserire `application/json`.
* `authorization`: chiave per chiamare l'API, nel formato `Bearer {token}`.
* `content-type`: inserire `application/json`.

**Request Body**

| Parametro | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `action` | string | No | Tipo di operazione, `retrieve` (predefinito, per interrogare singolarmente) o `retrieve_batch` (per interrogazione in batch) |
| `id` | string | No | ID del compito da interrogare (il `task_id` restituito durante la creazione del video) |
| `trace_id` | string | No | ID di tracciamento del compito da interrogare, può sostituire `id` |
| `ids` | string\[] | No | Elenco degli ID dei compiti da interrogare in batch, da utilizzare con `retrieve_batch` |

> Quando si interroga un singolo compito, è necessario fornire almeno uno tra `id` e `trace_id`.

## Interrogare un singolo compito

### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve",
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}'
```

### Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/dreamina/tasks"

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

payload = {
    "action": "retrieve",
    "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}

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

### Esempio di risposta

Se la richiesta ha successo, l'API restituisce i dettagli di quel compito. `request` è il corpo della richiesta durante la creazione del compito, `response` è il corpo della risposta dopo il completamento del compito, dove `data.video_url` è l'indirizzo del video digitale generato:

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "started_at": 1769262721.823,
  "finished_at": 1769262769.123,
  "elapsed": 47.3,
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "request": {
    "model": "omnihuman-1.5",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  },
  "response": {
    "success": true,
    "data": {
      "task_id": "362b4fed67bd11f1ad1100163e57d510",
      "status": "done",
      "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
      "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
      "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
    }
  }
}
```

Descrizione dei campi:

* `id`: ID unico per il compito di generazione video.
* `trace_id`: ID di tracciamento per questa richiesta, utilizzato per la risoluzione dei problemi.
* `request`: contenuto della richiesta inviato durante la creazione del compito.
* `response`: contenuto della risposta restituito dopo il completamento del compito. Quando `response.data.status` è `done`, `response.data.video_url` è l'indirizzo video finale.
* `created_at`: data e ora di creazione del compito, timestamp Unix (secondi, float).
* `started_at`: data e ora di inizio esecuzione del compito, timestamp Unix (secondi, float).
* `finished_at`: data e ora di completamento del compito, timestamp Unix (secondi, float). Questo campo non viene restituito se il compito non è completato.
* `elapsed`: tempo di esecuzione del compito, in secondi (float, con 3 decimali). Questo campo non viene restituito se il compito non è completato.

> Se il compito non è ancora completato, `status` potrebbe non essere in stato `done`; se il compito non esiste o non ha ancora generato risultati, l'interfaccia restituirà un oggetto vuoto `{}`, si prega di riprovare più tardi.

## Interrogazione di compiti in batch

Imposta `action` su `retrieve_batch` e passa l'array `ids`:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "ids": [
    "362b4fed-67bd-11f1-ad11-00163e57d510",
    "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70"
  ]
}'
```

Nella risposta, `items` è un array di dettagli dei compiti in batch (ogni elemento ha lo stesso formato del risultato di una singola interrogazione), `count` è il numero di compiti restituiti in questa richiesta.

## Gestione degli errori

Quando si verifica un errore durante la chiamata all'API, verrà restituito il codice di errore e il messaggio corrispondente:

* `400 bad_request`: errore di richiesta, potrebbero mancare parametri necessari come `id` / `trace_id`.
* `401 invalid_token`: non autorizzato, il token di autorizzazione è invalido o mancante.
* `429 too_many_requests`: troppe richieste, superato il limite di velocità.
* `500 api_error`: errore interno del server.

### Esempio di risposta di errore

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "id or trace_id is required to retrieve a task"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusione

Attraverso questo documento, hai appreso come utilizzare l'API Dreamina Tasks per interrogare i risultati di compiti video digitali singoli o in batch. Combinando l'interfaccia di generazione con il `callback_url` / `async` in modalità asincrona, puoi realizzare un polling stabile. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.