Vai al contenuto principale
Maestro è un’interfaccia di produzione video nativa per Agent: descrivi il video desiderato con un prompt in linguaggio naturale (facoltativamente allegando immagini / video / audio di riferimento tramite file_urls), e un “regista AI” senza interfaccia completerà automaticamente la scelta dell’argomento, la scrittura della sceneggiatura, la generazione delle immagini, il doppiaggio, la musica di sottofondo, il compositing e il rendering, producendo infine un video completo con sottotitoli e caricandolo sulla CDN. Questo articolo introdurrà nel dettaglio la guida all’integrazione dell’API di generazione video Maestro, aiutandovi a integrarla rapidamente e a sfruttarne appieno le funzionalità. Questa è un’interfaccia di attività asincrona: dopo l’invio, restituirà immediatamente task_id; successivamente, utilizza la API di query delle attività Maestro (POST /maestro/tasks) per effettuare il polling e ottenere il risultato (il polling è gratuito e non viene addebitato). Per continuare a iterare su un video esistente, puoi utilizzare action: remix / edit / extend insieme a ref_task_id.

Processo di richiesta

Per utilizzare l’API di generazione video Maestro, ottieni innanzitutto il tuo API Token dalla console Ace Data Cloud e conservalo come riserva. Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per registrarti e accedere; al termine tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza bisogno di richiederne uno separatamente per ogni servizio. La prima richiesta include crediti gratuiti, consentendo una prova gratuita; quando i crediti non sono sufficienti, puoi ricaricare il saldo universale nella console.
📘 Documentazione completa: API di generazione video Maestro →

Utilizzo di base

POST https://api.acedata.cloud/maestro/videos Per l’utilizzo più semplice, basta passare una descrizione in linguaggio naturale a prompt: il regista AI deciderà automaticamente sceneggiatura, immagini, doppiaggio e montaggio. Vediamo innanzitutto le intestazioni e il corpo della richiesta da impostare. Intestazioni della richiesta includono:
  • accept: il formato in cui si desidera ricevere la risposta; inserire qui application/json, ovvero il formato JSON.
  • authorization: la chiave per chiamare l’API, selezionabile direttamente dal menu a discesa dopo averla richiesta.
  • content-type: il formato del corpo della richiesta; inserire qui application/json.
Corpo della richiesta include principalmente:
  • prompt: descrizione in linguaggio naturale del video da realizzare (tema, cosa mostrare, stile e pubblico).
  • langs: array delle lingue del video finale; trasmettere una sola lingua alla volta, ad esempio ["zh-cn"]. Il valore predefinito è ["zh-cn"].
  • aspect: proporzioni dell’immagine, 9:16 (predefinito) / 16:9 / 1:1.
  • duration: durata desiderata (secondi); il valore predefinito è 30.
Tutti i campi del corpo della richiesta sono mostrati nella tabella seguente: Di seguito viene illustrato un esempio concreto. Supponiamo di voler generare un breve video divulgativo in cinese, verticale e della durata di 20 secondi. Il codice CURL corrispondente è il seguente:
Il codice Python corrispondente è il seguente:
Facendo clic su Esegui, è possibile notare che si ottiene immediatamente un risultato, come segue:
Di seguito è riportata la descrizione dei campi del risultato restituito:
  • success: indica se questa attività è stata inviata correttamente.
  • task_id: ID di questa attività di generazione video; utilizzalo successivamente per interrogare periodicamente il risultato tramite l’API di query delle attività Maestro.
  • trace_id: ID di tracciamento di questa richiesta; in caso di problemi, può essere fornito al supporto tecnico per facilitarne l’identificazione.
Poiché la produzione del video richiede molto tempo, l’interfaccia restituisce immediatamente task_id e non attende il completamento del rendering del video. Successivamente, è necessario usare task_id per effettuare il polling del risultato; per i dettagli, vedere la sezione «Ottenere il risultato».

Specificare il tipo e lo stile del video (scenario / style)

Quando scenario non viene passato, viene determinato automaticamente dall’AI (equivale a auto); se si desidera fissare il video a un determinato tipo, passarlo esplicitamente. Ad esempio, per creare un cortometraggio verticale, è possibile specificare quanto segue:
  • scenario: tipo di video, qui impostato su drama (cortometraggio con personaggi + dialoghi).
  • style: stile visivo, qui impostato su cinematic (qualità cinematografica).
Il codice CURL dell’esempio di compilazione è il seguente:
Modalità di abbinamento comuni:
  • Cortometraggio narrato: scenario: "narrated".
  • Sottotitoli automatici: scenario: "captions", è necessario usare file_urls per passare il video sorgente.
  • Avatar digitale / presentazione parlata: scenario: "avatar", è necessario usare file_urls per passare un’immagine ritratto.
  • Cortometraggio: scenario: "drama" (personaggi + dialoghi).
  • style è una preimpostazione dello stile visivo (come modern / neon / luxury), non modifica il tipo e influenza solo l’aspetto.
  • voice viene utilizzato per specificare il timbro della voce narrante (come warm-female / deep-male), non è legato alla lingua ed è universale tra le lingue.
Il risultato restituito è coerente con «Utilizzo di base», e restituisce immediatamente anch’esso task_id.

Lingua del video finale

Un’attività consegna solo un video finale in una sola lingua. langs può contenere solo un codice lingua, come ["zh-cn"] o ["en"]; il passaggio di più lingue restituirà 400. Se sono necessari video in lingue diverse, creare attività separate. La selezione della lingua non modifica il prezzo al secondo.

Iterare su un video esistente (remix / edit / extend)

Passando action e il ref_task_id dell’attività precedente, è possibile apportare modifiche incrementali sulla base del progetto originale (come «modificare il titolo della scena 2», «cambiare il doppiaggio», «scurire l’insieme»). Le piccole modifiche sono rapide, mentre le grandi modifiche verranno rifatte:
  • remix: reinterpretare sulla struttura del video originale (mantenere il tema, modificare la presentazione).
  • edit: rifinire una parte specificata (come cambiare il titolo, il doppiaggio o la gradazione colore).
  • extend: estendere il contenuto sulla base del video originale.
Il risultato restituito restituisce immediatamente anch’esso un nuovo task_id, che può essere usato per l’interrogazione per ottenere il video finale dopo l’iterazione.

Ottenere i risultati

Poiché la produzione video richiede molto tempo, questa interfaccia restituisce immediatamente task_id dopo l’invio; è necessario usarlo per interrogare i risultati tramite l’API di query delle attività Maestro:
Al completamento dell’attività verranno restituite le informazioni di un video finale (nell’array variants). status passerà attraverso pending → planning → producing → succeeded (oppure failed), l’interrogazione è gratuita e non consuma crediti. Per il formato di risposta completo e la query dell’elenco cronologico, fare riferimento alle istruzioni di integrazione dell’API di query delle attività Maestro.

Fatturazione

Dopo il successo dell’attività, la fatturazione avviene in base alla durata effettiva del video finale consegnato; in caso di errore non viene addebitato alcun costo. La durata fatturabile viene calcolata in secondi interi e non supera la durata richiesta; quando non è possibile leggere la durata del video finale, viene usata come fallback la durata richiesta. L’invio dell’attività stesso non viene fatturato separatamente, l’interrogazione di /maestro/tasks è gratuita.
Tutti gli scenari, le azioni e le lingue adottano lo stesso prezzo, senza moltiplicatori per scenario o supplementi per lingua. Ogni attività consegna solo un video finale in una sola lingua. La durata obiettivo richiesta supporta 5–300 secondi, con output uniforme a 1080p / 30fps.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice e il messaggio di errore corrispondenti. Ad esempio:
  • 400 invalid_request: Richiesta non valida, probabilmente a causa di un prompt mancante o di parametri non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 403 forbidden: Vietato, saldo o accesso insufficiente.
  • 429 too_many_requests: Troppe richieste, è stato 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, avete già compreso come utilizzare l’API di generazione video Maestro: basta un prompt in linguaggio naturale per completare automaticamente sceneggiatura, materiali, doppiaggio, musica di sottofondo, montaggio, sottotitoli e rendering del video finale, con supporto per specificare tipo di video, stile, timbro vocale, lingua del video finale e iterazioni su video esistenti. Ci auguriamo che questo documento possa aiutarvi a integrare e utilizzare meglio questa API. In caso di domande, non esitate a contattare il nostro team di supporto tecnico.

Interfacce correlate