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 inserisciapplication/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 inserisciapplication/json.
Esempio di codice
Il codice CURL 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’arrayvariants contiene un video finale):
id: l’ID di questa attività video, utilizzato per identificare in modo univoco l’attività di generazione video.status: lo stato dell’attività, con valorepending → planning → producing → succeeded(oppurefailed). Per verificare se l’attività è stata completata, fare riferimento al campostatusdi 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à;stageemessageriflettono l’evento di avanzamento più recente del regista IA (pertanto, dopo il completamento,stagepotrebbe ancora corrispondere all’ultima fase di esecuzione, ad esempioproducing) 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, inclusilang,aspect,title,output_url(URL per il download del video finale) e altri campi.data.project: artefatti dell’intero progetto, inclusitarball_url(pacchetto del progetto) eoutputs(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
Passandoaction: 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:count: il numero totale di attività visibili all’esecutore attualmente autenticato, non influenzato dalle condizioni temporali o dalimit.items: l’array di attività filtrato in base alle condizioni temporali e alimit, 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
- Istruzioni di integrazione dell’API di generazione video Maestro: utilizza un prompt in linguaggio naturale per produrre automaticamente un video finale con sottotitoli; dopo l’invio restituisce
task_id, quindi utilizza questa interfaccia per effettuare il polling del risultato.

