Passa al contenuto principale

Generazione video e audio

Libre WebUI 0.18.0 estende la generazione oltre le immagini: i plugin dei provider possono dichiarare funzionalità video e audio e tutto ciò che viene generato — immagini, video, voce e suoni — confluisce in un'unica galleria multimediale per utente.

La generazione multimediale è disponibile a ogni utente autenticato. La galleria è rigorosamente per utente: ogni lettura, recupero di contenuto ed eliminazione è limitato all'account connesso.

Blocchi delle funzionalità dei plugin​

Una definizione di plugin dichiara ogni funzionalità multimediale in un blocco distinto:

"capabilities": {
  "image": { "endpoint": "...", "model_map": ["..."], "config": { ... } },
  "tts":   { "endpoint": "...", "model_map": ["..."], "config": { ... } },
  "audio": { "endpoint": "...", "model_map": ["..."], "config": { ... } },
  "video": { "endpoint": "...", "model_map": ["..."], "config": { ... } }
}

Ogni blocco contiene un endpoint, un elenco model_map di riserva, un models_endpoint facoltativo per il rilevamento in tempo reale dei modelli e un oggetto config con opzioni specifiche della funzionalità: dimensioni e proporzioni per le immagini, voci e formati per il parlato, risoluzioni, proporzioni e durate per i video. Un provider video può inoltre dichiarare un cancel_endpoint basato sull'ID del prompt e un cancel_method; Libre non deduce il supporto dell'annullamento da un normale endpoint di generazione.

Esistono due funzionalità audio ed entrambe confluiscono nella galleria come audio:

  • tts è parlato: il testo viene letto ad alta voce con una voce selezionata.
  • audio è suono: un modello genera contenuto audio da un prompt.

OpenRouter (plugins/openrouter.json) è attualmente l'unico plugin incluso che dichiara blocchi video e audio. Quando è presente un models_endpoint, l'elenco dei modelli viene aggiornato durante il normale ciclo di rilevamento (consulta Variabili di ambiente per le impostazioni TTL del rilevamento); model_map resta l'alternativa di riserva.

Generare contenuti multimediali​

Apri Immagina (/gallery). L'intestazione offre Genera per le immagini, quando la generazione di immagini è abilitata nelle Impostazioni, oltre ai pannelli Video e Audio.

La generazione di voce e suoni è sincrona: viene eseguita la richiesta, il risultato viene salvato nella galleria e la risposta restituisce l'elemento completato. Annulla interrompe la richiesta del browser e quella in uscita da Libre verso il provider; un risultato annullato non viene salvato. La generazione di immagini segue lo stesso contratto di annullamento alla disconnessione.

Per un flusso di lavoro ComfyUI accettato, Libre invia sia l'operazione di annullamento del processo tramite ID del prompt sia l'eliminazione dalla coda tramite ID del prompt, quindi attende fino a tre secondi che la rimozione termini prima di liberare la richiesta. Non chiama mai l'operazione di interruzione senza ambito di ComfyUI, che potrebbe arrestare il flusso di lavoro di un altro utente. Le versioni attuali di ComfyUI espongono /api/jobs/:promptId/cancel per un flusso di lavoro in esecuzione. Su una versione precedente priva di tale operazione, Libre può comunque rimuovere esattamente l'elemento in attesa dalla coda, ma non può arrestare in sicurezza un flusso di lavoro già in esecuzione; aggiorna ComfyUI per ottenere il contratto di annullamento completo.

I plugin TTS possono inoltre dichiarare la clonazione vocale. Per tali modelli, il pannello Audio mostra il caricamento di un audio di riferimento e, quando richiesto dal provider, un campo per la trascrizione esatta. Libre WebUI convalida i limiti di tipo e dimensione del file indicati nel manifesto, conserva il caricamento in memoria e lo inoltra soltanto al provider selezionato. Solo il parlato generato viene inserito nella galleria.

Una voce clonata può essere facoltativamente salvata come voce riutilizzabile e dotata di nome per lo stesso plugin e modello. Il salvataggio richiede una conferma separata del consenso all'archiviazione. Libre WebUI crittografa il riferimento originale e la trascrizione in un profilo vocale di proprietà dell'utente; non usa il parlato generato come riferimento. I profili salvati possono essere selezionati o eliminati definitivamente in Impostazioni → Sintesi vocale. Il provider configurato riceve nuovamente il riferimento archiviato ogni volta che genera un batch di parlato. Il profilo è associato al routing approvato di tale provider; se cambia la definizione del plugin o l'endpoint, ricrea il profilo per acconsentire alla nuova destinazione. Usa soltanto registrazioni di persone che hanno acconsentito sia alla richiesta di clonazione sia all'eventuale archiviazione richiesta.

I profili vocali sono esclusi intenzionalmente dall'esportazione generale dei dati di Libre WebUI perché contengono materiale biometrico sorgente. Se ti serve il ripristino di emergenza, esegui insieme il backup del database crittografato dell'applicazione e di ENCRYPTION_KEY; altrimenti ricrea i profili dalle registrazioni originali ottenute con consenso.

Ciclo di vita dei processi video​

La generazione di video è asincrona. L'invio di un processo (POST /api/media/video/generate) restituisce 202 con un record del processo, che passa da pending a in_progress e infine a completed oppure failed.

  • Dopo la convalida, l'invio viene scollegato dalla risposta del browser. Libre conserva l'ID del processo del provider immediatamente dopo l'accettazione, anche se il pannello o la connessione di rete si chiude mentre il provider sta rispondendo.
  • GET /api/media/video/jobs elenca soltanto gli handle salvati dell'utente autenticato; ogni volta che viene aperto, il pannello richiede fino a 100 handle attivi. Un processo in sospeso può quindi essere riaperto dopo una navigazione, un aggiornamento o una disconnessione.
  • Un processo permanente media.video.resume.v1 interroga il provider e scarica un risultato completato anche quando il pannello è chiuso. In modalità individuale, l'handler viene eseguito nel worker incorporato; in modalità team, nel worker esterno. Lease, tentativi limitati, nuova convalida dell'attore e completamento condizionale consentono a un altro worker di recuperare il processo dopo la chiusura di un processo, senza creare una riga duplicata nella galleria o un riferimento blob duplicato. Gli endpoint resume/GET esistenti restano confini di compatibilità e stato; l'interfaccia può continuare a interrogarli per la visualizzazione.
  • La chiusura del pannello o la selezione di Interrompi attesa annulla soltanto il trasporto corrente per lo stato o il download. Un'azione Annulla processo lato provider appare soltanto quando il plugin dichiara esplicitamente un endpoint di annullamento basato sull'ID del processo. Quando il provider conferma l'annullamento, Libre rimuove l'handle locale salvato.
  • Al completamento, il backend scarica il video (limite di 200 MB, i reindirizzamenti HTTP non vengono seguiti) e lo salva nella galleria.
  • Il record del processo archivia plugin, modello, opzioni, stato e prompt (crittografato quando archiviato). I record dei processi completati o non riusciti più vecchi di 30 giorni vengono eliminati in modo opportunistico; tale pulizia non fa scadere gli handle in sospeso.
  • Gli stati terminali generano notifiche: un video completato pubblica una notifica media-ready, mentre un errore del provider pubblica media-failed; entrambe rimandano alla galleria, sono deduplicate per processo e vengono distribuite tramite la casella interna all'app e gli eventuali webhook abbonati.

Modifica delle immagini e inpainting​

Le immagini della galleria per cui è configurato un modello capace di modificarle ottengono l'azione Modifica immagine. L'editor disegna una maschera direttamente sull'immagine: le aree dipinte vengono ridipinte dal modello, mentre una tela non modificata applica la modifica all'intera immagine; può inoltre allegare altre immagini di riferimento per la composizione quando il modello accetta più di un input. La modifica usa il contratto multipart compatibile con OpenAI per gli edit: un plugin vi partecipa dichiarando edit_endpoint nella configurazione della funzionalità immagine, insieme ai limiti facoltativi supports_mask, max_reference_images, edit_mime_types e max_edit_image_bytes (il manifesto OpenAI incluso li dichiara tutti).

Ogni input viene convalidato prima che qualsiasi byte lasci il processo: MIME dichiarato, magic byte rilevati (PNG, JPEG o WebP) e limite di 10 MiB per immagine; le maschere devono essere PNG perché soltanto PNG contiene il canale alfa che contrassegna le aree da ridipingere. I risultati vengono salvati nella galleria con metadati di provenienza che registrano l'elemento sorgente della galleria, il numero di immagini di riferimento caricate e l'eventuale uso di una maschera. Le modifiche vengono misurate esattamente come le generazioni.

Galleria unificata​

La galleria elenca tutti i tipi di contenuto multimediale intercalati per data di creazione, con filtri per Tutto, Immagini, Video e Audio. Video e audio vengono riprodotti direttamente; le immagini si aprono nel lightbox; ogni elemento può essere scaricato o eliminato. Gli amministratori possono attivare la conservazione automatica con GALLERY_RETENTION_DAYS: l'operazione pianificata elimina i contenuti più vecchi della finestra seguendo lo stesso ciclo di eliminazione permanente di un'eliminazione manuale. Se non impostata, come per impostazione predefinita, i contenuti vengono conservati finché il proprietario non li elimina.

Archiviazione e distribuzione sono intenzionalmente prudenti:

  • I contenuti multimediali vengono archiviati in forma crittografata nel database dell'applicazione, sotto DATA_DIR, non come file separati su disco. Esegui insieme il backup del database e di ENCRYPTION_KEY, come per tutti i dati crittografati.
  • Le risposte API non incorporano mai i payload multimediali; gli elementi fanno invece riferimento a un URL del contenuto specifico per elemento.
  • Il contenuto distribuito deve corrispondere a un elenco consentito di MIME per tipo e al tipo archiviato, è limitato a 200 MB e viene inviato con X-Content-Type-Options: nosniff e una Content-Security-Policy che applica la sandbox alla risposta.

Gli endpoint precedenti dedicati alle sole immagini e il pannello di generazione delle immagini continuano a funzionare senza modifiche e scrivono nella stessa galleria.

Limiti di frequenza​

L'API multimediale applica un limite di frequenza per client:

OperazioneLimite
Generazione (video, parlato, suono)10 richieste al minuto
Verifica dei processi video60 richieste al minuto
Elenco, contenuto ed eliminazioni della galleria120 richieste al minuto

L'interrogazione dell'interfaccia ogni 30 secondi resta ampiamente entro il limite previsto.

Misurazione e privacy​

Le chiamate di generazione multimediale vengono misurate nelle analisi dell'utilizzo riservate agli amministratori, come tutte le altre chiamate in uscita verso i provider: plugin, modello, stato, durata e conteggi delle unità. Prompt e contenuti generati non vengono mai scritti nei record di utilizzo. Il contenuto multimediale generato e il prompt del processo video esistono soltanto nelle righe crittografate dell'utente.

Come per la chat, il provider configurato riceve il prompt e restituisce il contenuto; si applicano prezzi, criteri di conservazione e criteri sui contenuti del provider.

Documentazione correlata​