> ## 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. # Documentazione per l'integrazione dell'API di query delle attività Maestro > Maestro AI Video Studio API guide - Ace Data Cloud La funzione principale dell'API di query delle attività Maestro consiste nell'utilizzare l'ID dell'attività restituito dall'[API di generazione video Maestro](/it/guides/maestro/maestro_videos) (`POST /maestro/videos`) per interrogare lo stato di esecuzione e il risultato finale dell'attività. Questo documento illustrerà in dettaglio la documentazione per l'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` ## Procedura di richiesta Per utilizzare l'API di query delle attività Maestro, innanzitutto vai alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare come riserva. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Se non hai ancora effettuato l'accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; al termine tornerai automaticamente alla pagina corrente. **Un solo API Token può chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio.** La prima richiesta include crediti gratuiti, per provare il servizio gratuitamente; quando i crediti sono insufficienti, puoi ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [API di query delle attività Maestro →](https://platform.acedata.cloud/documents/maestro-tasks) ## Query di una singola attività Per sapere come creare un'attività video, consulta la documentazione [API di generazione video Maestro](/it/guides/maestro/maestro_videos). Prendiamo come esempio uno degli ID attività restituiti: `f57e99c4f60f4373a15517742ce2357d`, per dimostrare come consultarne lo stato e il risultato. ### Impostare le intestazioni della richiesta e il corpo della richiesta Le **Request Headers** includono: * `accept`: specifica la ricezione di risultati di risposta in formato JSON, qui impostato su `application/json`. * `authorization`: la chiave per chiamare l'API, che può essere selezionata direttamente dal menu a discesa dopo la richiesta. * `content-type`: il formato del corpo della richiesta, qui impostato su `application/json`. Il **Request Body** include: | Campo | Tipo | Obbligatorio | Descrizione | | - | - | - | - | | `id` | string | obbligatorio quando si interroga una singola attività | Il `task_id` restituito da `POST /maestro/videos` | | `action` | string | no | `retrieve` (predefinito, interroga una singola attività); quando si interroga l'elenco storico è fisso su `retrieve_batch` | ### Esempio di codice Il codice CURL corrispondente è il seguente: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "f57e99c4f60f4373a15517742ce2357d", "action": "retrieve" }' ``` Il codice Python corrispondente è il seguente: ```python theme={null} import requests url = "https://api.acedata.cloud/maestro/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "f57e99c4f60f4373a15517742ce2357d", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Esempio di risposta Dopo che la richiesta è riuscita, l'API restituirà lo stato e il risultato dell'attività video. L'esempio di risposta quando l'attività è completata è il seguente (a ogni lingua corrisponde un `variant`): ```json theme={null} { "id": "f57e99c4f60f4373a15517742ce2357d", "started_at": 1769262721.823, "finished_at": 1769264698.3, "elapsed": 1976.477, "status": "succeeded", "progress": { "percent": 100, "stage": "producing", "message": "rendering scene 2" }, "request": { "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点", "langs": [ "zh-cn", "en" ], "aspect": "9:16", "duration": 20 }, "response": { "success": true, "data": { "variants": [ { "lang": "zh-cn", "aspect": "9:16", "kind": "video", "title": "什么是向量数据库", "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001" }, { "lang": "en", "aspect": "9:16", "kind": "video", "title": "What is a vector database", "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002" } ], "project": { "tarball_url": null, "outputs": [ "https://…/zh.mp4", "https://…/en.mp4" ] }, "percent": 100, "stage": "producing", "progress": [ { "stage": "producing", "message": "rendering scene 2", "pct": 60, "t": 1750000000 } ] } } } ``` I campi del risultato restituito sono descritti di seguito: * `id`: l'ID di questa attività video, utilizzato per identificare univocamente questa attività di generazione video. * `status`: stato dell'attività, i valori sono `pending → planning → producing → succeeded` (o `failed`). Il completamento dell'attività dipende da questo `status` di primo livello. * `elapsed`: tempo già trascorso dall'attività (secondi). * `progress`: oggetto di avanzamento di primo livello, `percent` (0–100) verrà impostato a 100 in caso di successo dell'attività; `stage` e `message` riflettono l'evento di avanzamento più recente del regista AI (quindi dopo il successo `stage` potrebbe essere ancora l'ultima fase di esecuzione come `producing`), e possono essere utilizzati direttamente per visualizzare la barra di avanzamento. * `request`: il corpo della richiesta al momento dell'avvio dell'attività. * `response`: le informazioni di risposta dell'attività. * `success`: se l'attività ha avuto successo. * `data.variants`: a ogni lingua corrisponde un oggetto video finale, che include `lang`, `aspect`, `title`, `output_url` (indirizzo di download del video finale) e altro. * `data.project`: il prodotto dell'intero progetto, che include `tarball_url` (pacchetto del progetto) e `outputs` (tutti i link ai video finali). * `data.progress`: array di eventi di avanzamento aggiunti per fase (log append-only), che può essere utilizzato per visualizzare l'avanzamento dettagliato in tempo reale. * `created_at`: ora di creazione dell'attività, timestamp Unix (secondi). * `started_at`: ora di inizio esecuzione dell'attività, timestamp Unix (secondi). È null quando 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` è possibile ottenere le attività più recenti dell'esecutore attualmente connesso (in ordine decrescente di data di creazione), utilizzabile per la pagina dell'elenco «I miei video». L'elenco storico è isolato in base all'identità di accesso. Il **Request Body** include: | Campo | Tipo | Obbligatorio | Descrizione | | - | - | - | - | | `action` | string | Sì | Fisso su `retrieve_batch` | | `limit` | int | No | Numero di risultati restituiti, predefinito 20; l'intervallo valido è 1–100 | | `created_at_max` | int | No | Restituisce solo le attività strettamente precedenti a questo timestamp Unix (escluso il valore di confine, per la paginazione) | | `created_at_min` | int | No | Restituisce solo le attività strettamente successive a questo timestamp Unix (escluso il valore di confine) | ### Esempio di codice Il codice CURL corrispondente è il seguente: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve_batch", "limit": 20 }' ``` ### Esempio di risposta Dopo che la richiesta ha avuto successo, l'API restituirà l'elenco delle attività storiche dell'utente corrente: ```json theme={null} { "count": 2, "items": [ { "id": "f57e99c4f60f4373a15517742ce2357d", "started_at": 1769262721.823, "finished_at": 1769264698.3, "elapsed": 1976.477, "status": "succeeded", "progress": { "percent": 100, "stage": "producing", "message": "rendering scene 2" }, "request": { "prompt": "…", "langs": [ "zh-cn", "en" ], "aspect": "9:16", "duration": 20 }, "response": { "success": true, "data": { "variants": [ { "lang": "zh-cn", "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003" } ] } } } ] } ``` L'introduzione ai campi del risultato restituito è la seguente: * `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 dalle condizioni temporali e da `limit`, ordinato in ordine decrescente di tempo 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 di video richiede molto tempo, `status` passerà attraverso `pending → planning → producing → succeeded` (oppure `failed`). Si consiglia di effettuare il polling ogni 5–10 secondi, finché `status` non diventa `succeeded` o `failed`. È possibile utilizzare `progress.percent` al livello superiore per mostrare 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 le informazioni 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 fornito 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 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusione Attraverso questo documento, hai già compreso come utilizzare l'API di query delle attività Maestro per interrogare lo stato e i risultati 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. In caso di domande, contatta in qualsiasi momento il nostro team di supporto tecnico. ## Interfacce correlate * [Istruzioni di integrazione API per la generazione video Maestro](/it/guides/maestro/maestro_videos): utilizza un prompt in linguaggio naturale per produrre automaticamente un video completo con sottotitoli; dopo l'invio restituisce `task_id`, quindi utilizza questa interfaccia per effettuare il polling del risultato. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.