> ## 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.

# Maestro Video Generation API Integration Instructions

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro è un'interfaccia di produzione video **nativa per agenti**: puoi descrivere il video desiderato con una frase in linguaggio naturale `prompt` (opzionalmente allegando `file_urls` con immagini / video / audio di riferimento), un "regista AI" senza testa completerà automaticamente la scelta del tema, scriverà il copione, genererà le immagini, la voce fuori campo, la musica, la sintesi e il rendering, producendo infine un video con sottotitoli e caricandolo su CDN.

Questo documento fornirà una descrizione dettagliata dell'integrazione dell'API di generazione video di Maestro, aiutandoti a integrare rapidamente e sfruttare appieno le capacità di questa API.

Questo è un'interfaccia per **compiti asincroni**: dopo l'invio, verrà immediatamente restituito un `task_id`, quindi puoi utilizzare l'[API di query dei compiti di Maestro](/it/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) per ottenere i risultati tramite polling (il polling è gratuito e non comporta costi). 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 di Maestro, prima vai al [Pannello di controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente.

**Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio.** La prima richiesta ti darà un credito gratuito, permettendoti di provare senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel [pannello di controllo](https://platform.acedata.cloud/console/coin).

> 📘 Documentazione completa: [API di generazione video di Maestro →](https://platform.acedata.cloud/documents/maestro-videos)

## Utilizzo di base

`POST https://api.acedata.cloud/maestro/videos`

L'uso più basilare richiede solo di inviare un `prompt` in linguaggio naturale, il regista AI deciderà automaticamente il copione, le immagini, la voce fuori campo e il montaggio. Qui di seguito vediamo le intestazioni della richiesta e il corpo della richiesta da impostare.

**Request Headers** includono:

* `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`.

**Request Body** include principalmente:

* `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.

Tutti i campi del corpo della richiesta sono mostrati nella tabella seguente:

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `prompt` | string | Sì | Descrivi in linguaggio naturale il video da realizzare (tema, cosa mostrare, stile, pubblico). Copione, immagini, voce fuori campo e montaggio sono decisi dall'AI. |
| `action` | string | No | `generate` (predefinito, genera un nuovo video) / `remix` / `edit` / `extend` (iterare su un video esistente, deve essere usato con `ref_task_id`). |
| `ref_task_id` | string | No | Obbligatorio quando `action` è remix / edit / extend: `task_id` della storia da cui partire. |
| `file_urls` | string\[] | No | Media di riferimento (URL di immagini / video / audio), ad esempio immagini del prodotto, logo, o frammenti di materiale a cui aggiungere sottotitoli. |
| `langs` | string\[] | No | Lingue di output, come `["zh-cn", "en"]`, predefinito `["zh-cn"]`. La prima è la lingua principale; per ogni lingua aggiuntiva si riutilizzano le immagini, si aggiungono solo voce fuori campo + rendering, **ogni lingua aggiuntiva +6 punti**. |
| `aspect` | string | No | `9:16` (predefinito) / `16:9` / `1:1`, output unificato a 1080p/30fps. |
| `duration` | int | No | Durata target (secondi), predefinita 30, supporta **5–300 secondi**. La fatturazione avviene in base alla durata effettiva del video, ma non supera la durata richiesta. |
| `scenario` | string | No | Tipo di video: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` richiede il video sorgente, `avatar` richiede un'immagine del volto. |
| `style` | string | No | Preset di stile visivo: `auto` (predefinito) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, accetta anche testo libero come suggerimento. Non cambia il routing. |
| `voice` | string | No | Voce narrante (indipendente dalla lingua, utilizzabile in più lingue): `auto` (predefinito) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`. |

Di seguito un esempio concreto. Supponiamo di voler generare un breve video scientifico di 20 secondi in cinese e inglese, in formato verticale, il corrispondente codice CURL è il seguente:

```bash theme={null}
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
}'
```

Il corrispondente codice Python è il seguente:

```python theme={null}
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)
```

Cliccando su esegui, puoi notare che riceverai immediatamente un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

La descrizione dei campi del risultato restituito è la seguente:

* `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](/it/guides/maestro/maestro_tasks).
* `trace_id`：L'ID di tracciamento della richiesta, da fornire al supporto tecnico in caso di problemi.

Poiché la produzione video richiede tempo, l'API restituisce **immediatamente `task_id`** e non attende il completamento del rendering video. È necessario utilizzare `task_id` per interrogare i risultati, vedere la sezione "Ottenere risultati".

## Specificare tipo e stile del video (scenario / style)

Se non viene fornito `scenario`, l'AI lo determina automaticamente (equivalente a `auto`); se si desidera fissare il video su un certo tipo, è necessario specificarlo. Ad esempio, per creare un **dramma in verticale**, si possono specificare i seguenti contenuti:

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

Ecco un esempio di codice CURL:

```bash theme={null}
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
}'
```

Modalità di abbinamento comuni:

* 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.

Il risultato restituito è lo stesso della "utilizzo di base", restituisce immediatamente `task_id`.

## Output multilingue

Passando più lingue in `langs`, è possibile generare versioni multilingue in un'unica volta. La prima è la lingua principale, ogni lingua aggiuntiva **riutilizzerà lo stesso set di immagini**, aggiungendo solo doppiaggio + rendering, quindi **ogni lingua aggiuntiva costa solo +6 punti**. Esempio:

```bash theme={null}
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
}'
```

Al termine del compito, ogni lingua avrà un `variant` corrispondente nei risultati (vedere [API di query dei compiti di Maestro](/it/guides/maestro/maestro_tasks)).

## Iterare su video esistenti (remix / edit / extend)

Passando `action` e `ref_task_id` dell'ultimo compito, è possibile apportare modifiche differenziali sulla base del progetto originale (come "cambiare il titolo del secondo atto", "cambiare la voce", "scurire complessivamente"). Piccole modifiche sono rapide, grandi modifiche richiederanno un rifacimento:

```bash theme={null}
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.

Il risultato restituito è anch'esso un nuovo `task_id`, da utilizzare per interrogare e ottenere il video finale.

## Ottenere risultati

Poiché la produzione video richiede tempo, questa API restituisce immediatamente `task_id` dopo l'invio, è necessario utilizzarlo per interrogare i risultati tramite l'[API di query dei compiti di Maestro](/it/guides/maestro/maestro_tasks):

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

Al termine del compito, verranno restituite le informazioni sul video finale (ogni lingua corrisponde a un `variant`). `status` passerà da `pending → planning → producing → succeeded` (o `failed`), **l'interrogazione è gratuita e non consuma punti**. Per il formato completo della risposta e la consultazione della lista storica, fare riferimento alla [documentazione dell'API di query dei compiti di Maestro](/it/guides/maestro/maestro_tasks).

## Fatturazione

**La fatturazione avviene dopo il completamento del compito in base al video finale, i compiti falliti non vengono addebitati.** La fatturazione si basa sulla durata effettiva del video consegnato e sul numero di lingue, e la durata fatturabile non supererà la durata richiesta. Se una lingua non viene prodotta, non verrà addebitato il costo aggiuntivo di +6. L'invio del compito stesso non comporta costi separati, l'interrogazione tramite `/maestro/tasks` è gratuita.

I punti per un singolo video finale sono calcolati come segue:

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

Maestro fattura uniformemente **0.60 punti/secondo di video finale**, supporta durate da 5 a 300 secondi, fino a 4 lingue e output a 1080p / 30fps; tutte le azioni e scene sono utilizzabili.

Moltiplicatore di scena: `drama` 1.35× / `avatar` 1.15× / altri 1×.

| Esempio | Punti |
| - | -: |
| Lite 30 secondi | 6 |
| Standard 30 secondi | 18 |
| Standard 60 secondi | 36 |
| Standard 120 secondi | 72 |
| Pro 30 secondi | 36 |
| Pro 300 secondi | 360 |
| Ogni lingua aggiuntiva effettivamente consegnata | +6 |
| Interrogazione `/maestro/tasks` | Gratuita |

## Gestione degli errori

Durante la chiamata all'API, se si verifica un errore, l'API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:

* `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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusione

Attraverso questo documento, hai appreso come utilizzare l'API di generazione video di Maestro: basta una frase in linguaggio naturale `prompt` per completare automaticamente la sceneggiatura, i materiali, il doppiaggio, la musica, il montaggio, i sottotitoli e il rendering finale, supportando anche la specifica del tipo di video, stile, tonalità, output multilingue e iterazioni su video esistenti. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.

## Interfacce correlate

* [Istruzioni per l'integrazione dell'API di query delle attività di Maestro](/it/guides/maestro/maestro_tasks): 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.