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

# Development Dreamina Videos

> Dreamina API guide - Ace Data Cloud

## API di generazione video di personaggi digitali Dreamina

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

Generazione di video di personaggi digitali guidati da audio (OmniHuman 1.5). Fornisci una foto del personaggio e un audio di guida per generare un video in cui il personaggio parla e sincronizza le labbra.

### Intestazioni della richiesta

| Intestazione | Valore |
| - | - |
| `Authorization` | `Bearer <la tua API Key>` |
| `Content-Type` | `application/json` |

### Parametri della richiesta

| Parametro | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `model` | string | No | Modello, predefinito `omnihuman-1.5` |
| `image_url` | string | Sì | URL pubblico della foto del personaggio, si consiglia un'immagine chiara e frontale |
| `audio_url` | string | Sì | URL pubblico dell'audio di guida (mp3/wav), si consiglia \< 60 secondi |
| `prompt` | string | No | Controlla espressioni, emozioni, stabilità e stile |
| `mask_url` | string\[] | No | URL della maschera del soggetto, utilizzato per specificare l'oggetto da guidare in un'immagine con più persone |
| `callback_url` | string | No | Se fornito, restituisce immediatamente `task_id`, e richiamerà questo indirizzo dopo la generazione del risultato |
| `async` | boolean | No | Se impostato su `true`, restituisce immediatamente `task_id`, senza necessità di `callback_url`, tramite `/dreamina/tasks` per interrogare il risultato |

### Suggerimenti per l'input

* **Immagine**: effetto migliore con un ritratto frontale chiaro e ben illuminato; il viso deve essere visibile e occupare una proporzione adeguata dell'immagine.
* **Audio**: mp3/wav, deve essere accessibile pubblicamente. Si consiglia di mantenere la durata entro 60 secondi (1080p consigliato ≤30 secondi, 720p ≤60 secondi).
* Sia `image_url` che `audio_url` devono essere accessibili pubblicamente.

### Esempio di risposta

```json theme={null}
{
  "success": true,
  "task_id": "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": {
    "task_id": "362b4fed67bd11f1ad1100163e57d510",
    "status": "done",
    "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }
}
```

### Modalità asincrona e interrogazione

L'interfaccia restituisce per impostazione predefinita il video finale in modo sincrono. Per compiti più lunghi, è possibile utilizzare una delle due modalità asincrone:

* Fornire `callback_url`: l'interfaccia restituisce immediatamente `task_id`, e richiamerà questo indirizzo dopo la generazione del risultato.
* Fornire `async: true`: l'interfaccia restituisce immediatamente `task_id`, e poi tramite `POST /dreamina/tasks` (gratuito) si può interrogare il risultato per `task_id` o `trace_id`.

Per dettagli sul contratto di interrogazione, vedere [Dreamina Tasks API](https://platform.acedata.cloud/documents/dreamina-tasks-integration).

### Gestione degli errori

| Codice stato | codice | Significato |
| - | - | - |
| 400 | `bad_request` | Parametri mancanti o non validi (es. `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | Token di autorizzazione mancante o non valido |
| 403 | `forbidden` | Saldo/quote insufficienti, o autorizzazione non concessa |
| 429 | `too_many_requests` | Richieste eccessive, superato il limite di velocità |
| 500 | `api_error` | Errore interno del server |

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "image_url is required (a public URL of a portrait image)"
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

### Fatturazione

La fatturazione è basata sulla durata del video generato, il pacchetto massimo è di circa **¥1/secondo** (ad esempio, un video di 10 secondi costa circa ¥10).


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