Vai al contenuto principale
La funzione principale dell’API di query delle attività Maestro consiste nel recuperare, tramite l’ID attività restituito da Maestro API di generazione video (POST /maestro/videos), lo stato di esecuzione e il risultato finale di tale attività. Questo documento illustrerà in dettaglio la guida all’integrazione dell’API di query delle attività Maestro. Poiché la generazione video è un’attività asincrona, dopo l’invio è necessario utilizzare questa interfaccia per effettuare il polling e ottenere l’avanzamento e il video finale, il polling è gratuito e non consuma crediti. POST https://api.acedata.cloud/maestro/tasks

Processo di richiesta

Per utilizzare l’API di query delle attività Maestro, vai innanzitutto alla console di Ace Data Cloud per ottenere il tuo API Token e conservalo per uso futuro. Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per registrarti ed effettuare l’accesso; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separato per ogni servizio. Alla prima richiesta verrà assegnata una quota gratuita, che consente di provarlo gratuitamente; quando la quota è insufficiente, puoi ricaricare il saldo generale nella console.
📘 Documentazione completa: API di query delle attività Maestro →

Query di una singola attività

Per sapere come creare un’attività video, fai riferimento alla documentazione Maestro API di generazione video. Prendiamo come esempio uno degli ID attività restituiti: f57e99c4f60f4373a15517742ce2357d, per dimostrare come interrogare il suo stato e il suo risultato.

Impostare le intestazioni e il corpo della richiesta

Le Request Headers includono:
  • accept: specifica la ricezione di risultati di risposta in formato JSON; qui inserisci application/json.
  • authorization: la chiave per chiamare l’API, che dopo la richiesta può essere selezionata direttamente dal menu a discesa.
  • content-type: il formato del corpo della richiesta; qui inserisci application/json.
Il Request Body include:

Esempio di codice

Il codice CURL corrispondente è il seguente:
Il codice Python corrispondente è il seguente:

Esempio di risposta

Dopo l’esecuzione corretta della richiesta, l’API restituirà lo stato e il risultato di questa attività video. Di seguito è riportato un esempio di risposta al completamento dell’attività (l’array variants contiene un video finale):
Di seguito è riportata la descrizione dei campi del risultato restituito:
  • id: l’ID di questa attività video, utilizzato per identificare in modo univoco l’attività di generazione video.
  • status: lo stato dell’attività, con valore pending → planning → producing → succeeded (oppure failed). Per verificare se l’attività è stata completata, fare riferimento al campo status di primo livello.
  • elapsed: tempo trascorso dall’attività (secondi).
  • progress: oggetto di avanzamento di primo livello. percent (0–100) è pari a 100 dopo il completamento corretto dell’attività; stage e message riflettono l’evento di avanzamento più recente del regista IA (pertanto, dopo il completamento, stage potrebbe ancora corrispondere all’ultima fase di esecuzione, ad esempio producing) e possono essere utilizzati direttamente per visualizzare una barra di avanzamento.
  • request: corpo della richiesta al momento dell’avvio dell’attività.
  • response: informazioni restituite dall’attività.
    • success: indica se l’attività è stata completata correttamente.
    • data.variants: contiene un oggetto video finale nella lingua selezionata, inclusi lang, aspect, title, output_url (URL per il download del video finale) e altri campi.
    • data.project: artefatti dell’intero progetto, inclusi tarball_url (pacchetto del progetto) e outputs (collegamento al video finale).
    • data.progress: array di eventi di avanzamento aggiunti per fase (registro append-only), utilizzabile per mostrare un avanzamento dettagliato in tempo reale.
  • created_at: ora di creazione dell’attività, timestamp Unix (secondi).
  • started_at: ora di avvio dell’esecuzione dell’attività, timestamp Unix (secondi). È null se l’attività non è ancora iniziata.
  • finished_at: ora di completamento dell’attività, timestamp Unix (secondi). È null quando l’attività non è completata.

Query dell’elenco storico

Passando action: retrieve_batch, puoi ottenere le attività più recenti dell’esecutore attualmente connesso (in ordine decrescente di creazione), utilizzabili per la pagina elenco «I miei video». L’elenco storico è isolato in base all’identità di accesso. Il Request Body include:

Esempio di codice

Il codice CURL corrispondente è il seguente:

Esempio di risposta

Dopo che la richiesta ha avuto successo, l’API restituirà l’elenco delle attività storiche dell’utente corrente:
I campi del risultato restituito sono descritti come segue:
  • count: il numero totale di attività visibili all’esecutore attualmente autenticato, non influenzato dalle condizioni temporali o da limit.
  • items: l’array di attività filtrato in base alle condizioni temporali e a limit, ordinato in ordine decrescente di ora di creazione; il formato di ciascun elemento è coerente con il risultato restituito da «Query di una singola attività».

Suggerimenti per il polling

Poiché la produzione del video richiede molto tempo, status attraverserà pending → planning → producing → succeeded (oppure failed). Si consiglia di eseguire il polling una volta ogni 5–10 secondi, finché status non diventa succeeded o failed. È possibile utilizzare progress.percent di primo livello per visualizzare una barra di avanzamento in tempo reale. Il polling di questa interfaccia è gratuito e non consuma crediti.

Gestione degli errori

Durante la chiamata dell’API, se si verifica un errore, l’API restituirà il codice e il messaggio di errore corrispondenti. Ad esempio:
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 404 not_found: Attività non trovata, il task_id specificato non esiste.
  • 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

Conclusione

Attraverso questo documento, hai già appreso come utilizzare l’API di query delle attività Maestro per interrogare lo stato e il risultato di una singola attività, nonché per recuperare l’elenco delle attività storiche dell’utente corrente. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Per qualsiasi domanda, contatta in qualsiasi momento il nostro team di supporto tecnico.

Interfacce correlate