Maestro Video Generation API Integration Instructions

​

Processo di richiesta

📘 Documentazione completa: API di generazione video di Maestro →

​

Utilizzo di base

• accept: il formato della risposta desiderata, qui si compila con application/json, ovvero formato JSON.
• authorization: la chiave per chiamare l’API, che puoi selezionare direttamente dopo la richiesta.
• content-type: il formato del corpo della richiesta, qui si compila con application/json.

• prompt: descrivi in linguaggio naturale il video da realizzare (tema, cosa mostrare, stile, pubblico).
• langs: array delle lingue di output, come ["zh-cn", "en"], predefinito ["zh-cn"].
• aspect: rapporto d’aspetto, 9:16 (predefinito) / 16:9 / 1:1.
• duration: durata target (secondi), predefinita 30.

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'

import requests

url = "https://api.acedata.cloud/maestro/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}

• success：Se la richiesta è stata inviata con successo.
• task_id：L’ID del compito di generazione video, da utilizzare in seguito per interrogare i risultati tramite l’API di query dei compiti di Maestro.
• trace_id：L’ID di tracciamento della richiesta, da fornire al supporto tecnico in caso di problemi.

​

Specificare tipo e stile del video (scenario / style)

• scenario：Tipo di video, impostato su drama (dramma con personaggi + dialoghi).
• style：Stile visivo, impostato su cinematic (qualità cinematografica).

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Due coinquilini litigano e si riconciliano a causa di un gatto, tre atti di ribaltamento, finale caldo",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'

• Video narrati: scenario: "narrated", supportato da Lite / Standard / Pro.
• Sottotitoli automatici: scenario: "captions", è necessario fornire il video sorgente tramite file_urls, supportato da Lite / Standard / Pro.
• Avatar / Voce narrante: scenario: "avatar", è necessario fornire un’immagine tramite file_urls, supportato da Standard / Pro.
• Dramma: scenario: "drama" (personaggi + dialoghi), supportato solo da Pro.
• style è un preset di stile visivo (come modern / neon / luxury), non cambia il tipo, influisce solo sulla percezione visiva.
• voice serve a specificare il tono della voce narrante (come warm-female / deep-male), indipendente dalla lingua, utilizzabile in più lingue.

​

Output multilingue

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Presenta il nostro prodotto di assistenza clienti intelligente, evidenziando 3 punti chiave",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'

​

Iterare su video esistenti (remix / edit / extend)

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "Cambia il titolo di apertura con una frase più impattante, rendi i colori complessivamente più scuri"
}'

• remix：Rielaborare la struttura video originale (mantenendo il tema, modificando l’espressione).
• edit：Effettuare ritocchi su parti specifiche (come cambiare titolo, cambiare voce, modificare i colori).
• extend：Espandere il contenuto sulla base del video originale.

​

Ottenere risultati

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"
}'

​

Fatturazione

Punti = durata finale in secondi × 0.60 × moltiplicatore di scena + 6 × max(numero di lingue - 1, 0)

​

Gestione degli errori

• 400 invalid_request：Richiesta non valida, probabilmente a causa di un prompt mancante o parametri non validi.
• 401 invalid_token：Non autorizzato, token di autorizzazione non valido o mancante.
• 403 forbidden：Vietato, saldo insufficiente o accesso negato.
• 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

​

Interfacce correlate

• Istruzioni per l’integrazione dell’API di query delle attività di Maestro: utilizza POST /maestro/videos per interrogare lo stato e i risultati delle attività con il task_id restituito, o per estrarre l’elenco delle attività storiche (polling gratuito).