Development Dreamina Tasks

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

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

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

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:

{
  "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:

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

{
  "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.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Development Dreamina Tasks

Integrazione e utilizzo dell’API Dreamina Tasks

Processo di richiesta

Parametri di richiesta

Interrogare un singolo compito

CURL

Python

Esempio di risposta

Interrogazione di compiti in batch

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Integrazione e utilizzo dell’API Dreamina Tasks

​Processo di richiesta

​Parametri di richiesta

​Interrogare un singolo compito

​CURL

​Python

​Esempio di risposta

​Interrogazione di compiti in batch

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Integrazione e utilizzo dell’API Dreamina Tasks

Processo di richiesta

Parametri di richiesta

Interrogare un singolo compito

CURL

Python

Esempio di risposta

Interrogazione di compiti in batch

Gestione degli errori

Esempio di risposta di errore

Conclusione