Documentazione per l'integrazione dell'API di query delle attività Maestro

La funzione principale dell’API di query delle attività Maestro consiste nell’utilizzare l’ID dell’attività restituito dall’API di generazione video Maestro (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 per ottenere il tuo API Token, da conservare come riserva.

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.

📘 Documentazione completa: API di query delle attività Maestro →

Query di una singola attività

Per sapere come creare un’attività video, consulta la documentazione API di generazione video Maestro. 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:

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:

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):

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

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:

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

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

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Documentazione per l'integrazione dell'API di query delle attività Maestro

Procedura di richiesta

Query di una singola attività

Impostare le intestazioni della richiesta e il corpo della richiesta

Esempio di codice

Esempio di risposta

Query dell’elenco storico

Esempio di codice

Esempio di risposta

Suggerimenti per il polling

Gestione degli errori

Esempio di risposta di errore

Conclusione

Interfacce correlate

​Procedura di richiesta

​Query di una singola attività

​Impostare le intestazioni della richiesta e il corpo della richiesta

​Esempio di codice

​Esempio di risposta

​Query dell’elenco storico

​Esempio di codice

​Esempio di risposta

​Suggerimenti per il polling

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

​Interfacce correlate

Procedura di richiesta

Query di una singola attività

Impostare le intestazioni della richiesta e il corpo della richiesta

Esempio di codice

Esempio di risposta

Query dell’elenco storico

Esempio di codice

Esempio di risposta

Suggerimenti per il polling

Gestione degli errori

Esempio di risposta di errore

Conclusione

Interfacce correlate