API Media

Elenca i contenuti multimediali pronti dalla più recente, massimo 1000 per pagina. folder mantiene solo i file direttamente dentro una cartella multimediale (il suo ID), o con root solo quelli nella radice della libreria; un ID cartella ben formato che non nomina nessuna cartella non elenca nulla. next_cursor è la posizione dell’ultima riga restituita mentre ci sono altre righe; passalo come after, con gli stessi filtri, per la pagina successiva. next_cursor è null nell’ultima pagina

Genera un’immagine statica da un prompt, memorizzala come contenuto multimediale privato pronto del progetto e fatturane l’utilizzo. La POST risponde subito 202 con Operation, con o senza Prefer: respond-async, perché un proxy davanti all’API elimina una richiesta che non invia alcun byte per 100 s e un’immagine statica di alta qualità può richiedere più tempo.

Interroga GET /api/operations/{id} finché Operation non è succeeded, quando il suo result è {media_id, usage: {quality, credits, usd}} (MediaGenerationUsage), o failed, quando il suo error è il problema. Un rifiuto deciso prima di qualsiasi lavoro del fornitore (payment_required, reseller_generation_limit, rate_limited, not_ready, invalid_request) risponde comunque alla POST.

Non include mai byte immagine, b64_json, chiavi oggetto, URL firmati, URL vendor, costo vendor, token vendor o nome modello deployment. Il prompt è byte cliente e non viene ripetuto.

Prima che il prompt raggiunga il fornitore di immagini, il server aggiunge requisiti fissi di inquadratura: l’opera deve riempire il bordo del quadro, e non possono essere raffigurati televisori, monitor, schermi, display, cornici, bordi, montaggi, supporti, pareti, stanze, mockup di dispositivi, ombre o fotografie di insegne installate, e qualsiasi parola nel prompt del chiamante che descriva dove l’insegna sarà appesa o quale dispositivo la mostrerà è trattata come metadati di posizionamento e non come soggetto.

Le regole decorative e i bordi all’interno del design stesso restano disponibili. Il prompt del chiamante non viene mai riscritto o rimosso e viene memorizzato invariato. Idempotency-Key riproduce la stessa Operation, mai un secondo tentativo fatturato. I client non eseguono PUT né confermano i byte generati.

La resa memorizzata è WebP lossy (qualità 90) alla dimensione esatta di aspetto con un lato corto di 1080 px (16:9 è 1920x1080, 9:16 1080x1920, 1:1 1080x1080, 4:3 1440x1080, 3:4 1080x1440, 3:2 1620x1080, 2:3 1080x1620); la tela del fornitore è ritagliata al centro e riscalata a quella dimensione.

Il nome file è distintivo per generazione, generated-16x9-1a2b3c4d.webp, con il suffisso preso dall’id del contenuto multimediale. Recupera i byte con GET /api/media/{id}/content. Own-gen-then-upload rimane valido.

Su Standard, la rimanenza che non copre il doppio del costo fornitore dell’immagine fissa, arrotondato ai crediti interi, dopo il livello minimo introduttivo (meno 1.000.000 crediti fino al 2027-01-01, poi zero) restituisce payment_required, tranne che per SCREENRIG__ENVIRONMENT=development, e l’ammissione prima della chiamata al fornitore richiede una rimanenza sopra quel livello del minimo per qualità: 200 crediti per basso, 800 per medio, 2000 per alto.

Gli altri piani non vengono mai rifiutati per il saldo.

Un’organizzazione fatturata tramite un reseller viene rifiutata con reseller_generation_limit (402) non appena ai clienti delegati del suo reseller è stato fatturato il limite mensile di generazione di immagini ($100 a prezzo di listino mentre il reseller attende la revisione, $1,000 dopo, conteggiato per mese UTC), a meno che il credito proprio dell’organizzazione non copra l’immagine; una generazione già ammessa viene completata.

Una configurazione vuota del fornitore selezionato restituisce not_ready. Solo token di progetto. Una generazione in corso per organizzazione; ulteriore parallelismo è rate_limited.

Elenca tutte le cartelle multimediali nel progetto, massimo 1000, ordinate per nome. Le cartelle organizzano la libreria multimediale, e un selettore playlist by:folder riproduce i file direttamente dentro una cartella. Il parent_id di una cartella è null nella radice della libreria.

Costruisci l’albero da parent_id; la cartella di un file è Media.folder_id. library=true elenca invece le cartelle della Libreria dell’organizzazione (sola lettura; un selettore by:folder può indicarne una).

Crea una cartella media nella radice della libreria (parent_id nullo o assente) o dentro parent_id. I nomi sono privati di spazi, contengono da 1 a 100 caratteri Unicode senza controlli, non sono "." o ".." e possono ripetersi. Un’organizzazione contiene al massimo 1000 cartelle in tutti i suoi progetti (quota_exceeded) annidate al massimo 10 livelli (invalid_request). Emette media.folder_created.

Rinomina una cartella (nome) o spostala con tutto il contenuto (parent_id, null per la radice della libreria). Una cartella non può spostarsi in se stessa o in una cartella al suo interno, e lo spostamento deve mantenere ogni cartella entro 10 livelli (invalid_request). Una modifica aggiorna la revisione della cartella ed emette media.folder_updated; gli stessi valori sono un’operazione nulla.

If-Match protegge opzionalmente la revisione.

Elimina una cartella. Nulla al suo interno viene eliminato: i suoi file e cartelle vengono spostati nel genitore della cartella eliminata (la radice della libreria se non ne aveva uno), ogni file e cartella spostato avanza la sua revisione. Un selettore playlist by:folder che la nomina poi non corrisponde a nulla; gli schermi in riproduzione abbandonano quel primitivo alla prossima risoluzione del selettore.

Emette media.folder_deleted. If-Match protegge opzionalmente la revisione.

Sposta file (media_ids) e cartelle (folder_ids) in una cartella (folder_id), o nella radice della libreria se folder_id è null, in una singola richiesta tutto o niente di massimo 1000 ID. Ogni ID deve esistere (not_found). Una cartella non può spostarsi in se stessa o in una cartella al suo interno, e lo spostamento deve mantenere ogni cartella entro 10 livelli (invalid_request).

Gli elementi già nella destinazione restano come sono; ogni file e cartella spostati avanzano la loro revisione. Spostare file cambia cosa riproducono i selettori by:folder delle loro vecchie e nuove cartelle, dalla risoluzione del selettore successivo di ogni schermo; spostare una cartella non cambia i file propri di nessuna cartella. Emette media.moved.

Lo spostamento di una credenziale Propose rende ogni file spostato in sospeso e mette in coda la sua revisione media, e i selettori delle playlist approvate la risolvono con la cartella con cui è stata approvata fino all’approvazione della modifica da parte di una persona (docs/reviews.md).

Anteprima in sola lettura delle corrispondenze di immagini o video pronte di proprietà del progetto corrente. Restituisce l’ordinamento dei nomi file e la politica normalizzata; la riproduzione casuale si mescola a ogni nuovo ciclo sul lettore. Non avanza i cursori, non crea concessioni di contenuti, né modifica i manifesti. Più di 1024 corrispondenze restituisce invalid_request.

Imposta o cancella il tag o i tag dell’elemento media. La modifica del set di tag di una credenziale Propose rende l’elemento in sospeso e mette in coda la sua revisione media; i selettori delle playlist approvate lo risolvono con i tag con cui è stato approvato finché una persona approva la modifica (docs/reviews.md). Una patch che mantiene lo stesso set di tag si applica e l’elemento resta approvato.

Una persona connessa imposta i tag di un elemento multimediale. tags è il set completo nuovo, mantenuto ordinato: il singolo tag di un elemento, se presente, conta come uno dei suoi tag ed è sostituito con gli altri, quindi invialo di nuovo per mantenerlo. Un array vuoto cancella ogni tag, e un tag malformato o ripetuto, o più di 32, è invalid_request.

È la modifica tag che patchMedia fa sotto una credenziale Manage, nella sessione dashboard: la revisione media avanza di uno e media.updated riporta la persona come attore, indipendentemente dal cambiamento del set. Il cambiamento di una persona è live, mai una revisione.

I media in attesa di revisione da parte di una persona (review_state pending, lasciati da un caricamento o cambiamento con credenziali Propose) sono rifiutati con media_pending_review (409) e nulla cambia: decidi prima la revisione in Reviews, così una modifica tag non approva mai una proposta agente. I selettori playlist per tag osservano i nuovi tag al loro prossimo refresh del ciclo playlist.

Il corpo non ha altri membri. If-Match porta la revisione del media ed è obbligatorio (invalid_request se assente, revision_conflict se obsoleto). Solo sessione dashboard; gli agenti cambiano tag con patchMedia. listMedia con tag trova l’elemento tramite i nuovi tag.

Imposta quando un media può essere scelto dai selettori dinamici (all, tag e folder) che lo riproducono, oppure cancella la regola con availability null. La regola è quella della programmazione: from e until (civili, precisione al minuto, until escluso), occorrenze windows, monthly e dates e date except, lette nel fuso orario di ogni schermo che risolve il selettore.

Un file fuori dalla sua regola viene escluso dalla selezione al successivo confine del ciclo della playlist e ritorna quando la regola torna in vigore; il bordo di una finestra viene seguito entro un minuto dal ciclo successivo del Player. Nessuna revisione di playlist o manifest cambia. Gli id espliciti (selettore per id o ids) ignorano la regola, così come tutto ciò che non è un selettore dinamico.

Uno schermo offline mantiene l’ultima selezione finché non si riconnette. Impostare la regola che l’elemento ha già non cambia nulla. Una credenziale Propose non può impostarla (insufficient_access): decidere quando il media viene riprodotto spetta a una persona con accesso Manage. I media in attesa di revisione da parte di una persona vengono rifiutati con media_pending_review.

If-Match contiene la revisione del media ed è obbligatorio.

Sostituisce sul posto il file di un elemento multimediale pronto con un caricamento dichiarato (createMediaUpload) i cui byte sono stati scritti, invece di confermarlo come nuovo media.

Il media mantiene il suo id, quindi ogni playlist e ogni programmazione che lo cita riproduce il nuovo file senza essere riprogrammata, e i selettori di cartella, tag e tutti i media che lo scelgono lo riproducono alla loro prossima risoluzione. La sostituzione deve essere dello stesso tipo di file (immagine per immagine, video per video, audio per audio); un altro tipo dà invalid_request.

Una modifica del rapporto d’aspetto è consentita: il risultato dell’operazione contiene una voce warnings aspect_ratio_changed che indica le playlist che usano l’elemento. Valgono tutte le regole di caricamento (il limite di byte video del piano, i limiti di dimensione, la quota di archiviazione).

Il file in uso resta nella cronologia delle versioni del media (listMediaVersions) e conta nei byte archiviati finché la sua versione non viene eliminata. If-Match, se inviato, è la revisione del media letta dal chiamante (revision_conflict se obsoleta).

La risposta è l’operazione del caricamento, come per commitMediaUpload: interroga getOperation; il risultato di un’operazione riuscita è {media_id, id, version, warnings}. Byte identici al file in uso non sostituiscono nulla e fanno fallire l’operazione con resource_conflict.

Con Propose effettivo la sostituzione attende invece la revisione: l’operazione riesce con result.status pending_review e result.review_id, il media continua a riprodurre il suo file finché una persona non approva, e una sostituzione più recente dello stesso media prende il posto di quella in attesa.

Elenca le versioni di un elemento multimediale, dalla più recente, con la versione in uso per prima (current: true). Una versione è un file che l’elemento ha avuto: number è la sua epoca di contenuto più uno (1 per il caricamento, uno in più per ogni sostituzione, ripristino o modifica della sincronizzazione del media), e i suoi byte vengono conservati finché la versione non viene eliminata.

Leggi i byte di una versione con GET /api/media/{id}/content?version=N.

Elimina una versione precedente: il suo record sparisce, i suoi byte escono subito dai byte archiviati del progetto e il suo oggetto viene rimosso dopo 24 ore, a meno che un’altra versione o la versione in uso contenga lo stesso file. La versione in uso non può essere eliminata (resource_conflict) e nessuna versione può essere eliminata mentre una sostituzione del media attende la revisione.

Una versione eliminata non può essere ripristinata.

Rimette in uso una versione precedente come nuova versione, nella successiva epoca di contenuto del media: il media mantiene il suo id e la revisione avanza di uno, così ogni playlist e ogni programmazione che lo cita riproduce di nuovo quel file senza essere riprogrammata. La versione copiata resta nella cronologia e condivide i suoi byte; la nuova versione conta nei byte archiviati come ogni altra.

La versione in uso non può essere ripristinata (resource_conflict). If-Match, se inviato, è la revisione del media letta dal chiamante. Il corpo può contenere una nota. Con Propose effettivo il ripristino diventa una revisione: 202 pending_review, e il media mantiene il suo file finché una persona non approva.

Esporta la resa immutabile originale di proprietà del progetto autenticato. Il bearer progetto paga il credito normale richiesta API autenticata, e i byte risposta completati sono registrati come project_media_export egress. L’identificatore media non è mai authority: l’identificatore di altro progetto restituisce not_found.

L’API trasmette dallo storage privato e non pubblica mai una chiave oggetto, URL di storage o GET firmato. Il nome del file allegato è l’identificatore del contenuto multimediale più l’estensione canonica per il tipo di contenuto verificato. La lettura dei contenuti non viene mai rifiutata per il saldo.

Una sessione dashboard visualizza gli stessi byte inline: i byte completati sono registrati come dashboard_media egress, e la risposta è privata, no-cache così il browser ne conserva una copia e la convalida con If-None-Match. Una risposta bearer progetto resta privata, no-store.

Applica le stesse regole di proprietà del progetto, condizionali, di intervallo e di archiviazione privata di exportMediaContent senza aprire o trasferire la resa archiviata.

Lists the project's media sync accounts, newest first (200 per page; next_cursor continues). Each shows its tenant and client id, its state and its last test; the client secret is never returned, only whether one is set and its last four characters.

Aggiunge un account che sincronizza in lettura. kind microsoft365 memorizza le credenziali dell’app Microsoft Entra propria del progetto, così le sincronizzazioni possono leggere una cartella SharePoint o OneDrive for Business: config.tenant_id è l’ID della directory o il dominio principale del tenant (common, organizations e consumers vengono rifiutati), config.client_id l’ID applicazione dell’app, e secret il valore di uno dei segreti client dell’app; l’app richiede l’autorizzazione dell’applicazione Microsoft Graph Sites.Selected (concessa su ogni sito) o Files.Read.All, con il consenso dell’amministratore.

Al posto di quei tre, config.connection_id indica una connessione Microsoft del progetto (createConnection), in entrambe le modalità, che accede e conserva il segreto. kind canva accetta solo un nome: l’account è pending_consent e la risposta porta authorize_url, un link monouso (valido fino a authorize_expires_at) che la persona titolare dell’account Canva apre, connessa a Canva, per collegarlo tramite l’integrazione Canva di screenRIG.

La concessione appartiene al progetto, quindi le sue sincronizzazioni sopravvivono alla persona che l’ha collegata.

Un server senza l’integrazione Canva risponde 409 canva_not_configured. kind dropbox funziona come canva: l’account è pending_consent e authorize_url è un link monouso che la persona titolare dell’account Dropbox apre, dopo aver effettuato l’accesso a Dropbox, per concedere l’accesso in sola lettura (files.metadata.read, files.content.read, account_info.read, sharing.read).

Passa attraverso l’app Dropbox di screenRIG, oppure attraverso l’app Dropbox propria del cliente quando config.app_key la indica (PKCE, quindi senza app secret; l’app deve elencare https://API_ORIGIN/api/dropbox/callback come URI di reindirizzamento).

Un server senza l’app Dropbox di screenRIG risponde 409 dropbox_not_configured a un account dropbox senza app_key. kind google_drive è subito ready e legge le cartelle condivise con config.service_account_email: l’account di servizio di screenRIG, oppure quello proprio del cliente quando secret è la chiave JSON di quell’account di servizio.

Una cartella condivisa con l’account di servizio di screenRIG si sincronizza solo quando un membro del progetto con un’email verificata l’ha condivisa o ne è il proprietario. Un server senza l’account di servizio di screenRIG risponde 409 google_drive_not_configured a un account google_drive senza chiave. Un segreto è sigillato a riposo e non viene mai restituito né scritto nei log. Aggiunge media_sync_account.created.

Un nuovo tentativo identico con la stessa Idempotency-Key restituisce lo stesso account (un nuovo tentativo Canva o Dropbox riceve un nuovo link).

Un account di sincronizzazione media, con il segreto mascherato.

Changes the name, tenant, client id or secret; an omitted secret keeps the stored one. A change of credentials discards the last test. A Canva account takes only a name; media sync account connect renews its connection. Appends media_sync_account.updated. If-Match guards the revision.

Deletes the account. Refused 409 resource_conflict while a sync reads through it; the detail names those syncs. Deleting a Canva account also revokes its tokens at Canva (a failure to revoke is logged and does not undo the delete). Appends media_sync_account.deleted. If-Match guards the revision.

Signs in with the account's app and reports what Microsoft granted it: whether the credentials work and which Graph application permissions the token carries (Sites.Selected, Files.Read.All and the like). Sites.Selected is reported with a warning, because each site needs a grant for the app.

For a Canva account it reports whether Canva still accepts the connection. It does not judge a site's grant, a folder or a design, or consent beyond what the token carries. The result is stored as last_test. A failed check is ok false in the answer, not a problem.

Crea un nuovo link di consenso monouso (authorize_url, valido fino a authorize_expires_at) per un account Canva o Dropbox, da inviare alla persona titolare di quell’account, che lo apre dopo aver effettuato l’accesso a Canva o a Dropbox e concede l’accesso. Sostituisce qualsiasi link precedente.

Un account collegato resta collegato finché il nuovo consenso non è completato, quindi questa operazione rinnova anche una connessione (stato reconnect_required) o la sposta su un altro account Canva o Dropbox. Il link è una credenziale del consenso: invialo solo a quella persona.

Un server senza l’integrazione Canva risponde 409 canva_not_configured; un account Dropbox senza app_key su un server senza l’app Dropbox di screenRIG risponde 409 dropbox_not_configured.

Lists the Canva designs the connected person can see, most recently changed first (50 per page; continuation continues), optionally those matching query. Each shows its id, title, last change, page count and a view address. An account that is not connected is 409 canva_reconnect_required; a server without the Canva integration is 409 canva_not_configured.

Dove Canva invia la persona dopo che ha consentito (o rifiutato) l’accesso in un link di consenso.

It carries no credential: the one-time state in the query finds the Canva account, must be unexpired and is used once, in the same write that stores the connection. screenRIG exchanges the code (PKCE, client authentication with the integration's credentials), reads whose Canva account it is, seals the tokens and appends media_sync_account.connected.

The answer is a short page naming the account and the project it was connected to; an error, an unknown, expired or used state, or a refused code renders the same page with the reason and changes nothing. Answers only on the API host.

Dove Dropbox reindirizza la persona dopo che ha concesso (o rifiutato) l’accesso da un link di consenso.

Non porta alcuna credenziale: lo state monouso nella query individua l’account Dropbox, non deve essere scaduto e viene usato una sola volta, nella stessa scrittura che memorizza la connessione. screenRIG scambia il codice (PKCE, con l’app Dropbox di screenRIG o con l’app_key propria dell’account), legge di quale account Dropbox si tratta, sigilla i token e aggiunge media_sync_account.connected.

The answer is a short page naming the account and the project it was connected to; an error, an unknown, expired or used state, or a refused code renders the same page with the reason and changes nothing. Answers only on the API host.

Lists the project's media syncs, newest first (200 per page; next_cursor continues), optionally of one account_id or state. Each shows its source folder, the media folder it fills, its cadence, state, next run and the summary of its last run.

provider canva: legge il design (design è il suo id o il suo indirizzo canva.com/design/ID/...) tramite un account Canva connesso e memorizza la sincronizzazione, da eseguire ora.

Each run asks Canva for the design's last change and, when it moved, exports the pages (pages, default all; format png gives one image per page and mp4 one video) and imports them into the media folder, replacing the bytes of a page already imported under the same media id so the playlists that use it update; a page the design no longer has leaves play like a removed SharePoint file.

Un design che Canva non mostra più ferma la sincronizzazione nello stato error (errore di esecuzione design_unavailable) e mantiene i media.

Un design o una pagina che l’account non può vedere è 409 media_sync_source_refused. provider dropbox: url è l’indirizzo della cartella in Dropbox (https://www.dropbox.com/home/...), il link di una cartella condivisa che l’account collegato ha aggiunto al proprio Dropbox, oppure un percorso che inizia con /; viene letto una sola volta tramite un account Dropbox collegato e la sincronizzazione viene memorizzata, da eseguire subito.

Le cartelle in uno spazio del team vengono lette dalla radice del team. Ogni esecuzione riprende dalla posizione salvata di Dropbox nella cartella, quindi vengono lette solo le modifiche.

Una cartella che l’account non può aprire è 409 media_sync_source_refused; un account la cui connessione Dropbox non accetta più è 409 dropbox_reconnect_required. provider google_drive: url è l’indirizzo Google Drive della cartella (https://drive.google.com/drive/folders/ID) o il suo ID, condivisa (basta il ruolo Lettore) con il service_account_email dell’account.

Ogni esecuzione elenca la cartella e confronta il checksum di ogni file. I file di Google Documenti, Fogli e Presentazioni vengono saltati come unsupported_type. Una cartella che l’indirizzo non riesce ad aprire è 409 media_sync_source_refused.

Tramite l’account di servizio di screenRIG la cartella deve essere condivisa o di proprietà di un membro del progetto con un’email verificata (403 media_sync_sharer_not_member), e ogni esecuzione lo verifica di nuovo (l’errore di esecuzione sharer_not_member ferma la sincronizzazione nello stato error). provider sharepoint: legge l’indirizzo della cartella tramite l’account (un indirizzo di sito SharePoint come https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER, oppure un link di condivisione; l’app deve poterlo vedere: Sites.Selected richiede una concessione sul sito, un link di condivisione richiede Files.Read.All) e memorizza la sincronizzazione, da eseguire subito. folder_id è la cartella media in cui vengono salvati i file; senza di esso la sincronizzazione ne crea una con il nome della cartella di origine.

Each run imports the images (png, jpeg, webp, gif), videos (mp4, webm) and audio (mp3) directly in the source folder, replaces the bytes of a file that changed under the same media id so playlists that use it update, and takes a file removed at the source out of play: its media is deleted, or, while screens still hold it, moved to a Removed subfolder and deleted later.

Subfolders are ignored; other files are listed as skipped with the reason. every is the seconds between runs, 300 to 86400, default 900. A folder the provider refuses is 409 media_sync_source_refused and one it cannot reach is 500 media_sync_source_unavailable; nothing is stored. Appends media_sync.created.

Una sincronizzazione media, con il riepilogo dell’ultima esecuzione.

Changes the name, every (seconds between runs), state (active or paused; active also resumes a sync an error stopped) or folder_id. A new folder_id points the sync at another media folder and makes its next run read the whole source again, which puts every synced file there. Appends media_sync.updated. If-Match guards the revision.

Ferma la sincronizzazione e dimentica quale file di origine è diventato quale media. I media e la loro cartella restano. Aggiunge media_sync.deleted. If-Match protegge la revisione.

Rende la sincronizzazione dovuta ora e risponde 202; un worker la esegue entro circa 30 secondi e la risposta di GET /api/media-syncs/{id} mostra il suo last_run.

Una sincronizzazione fermata da un errore viene eseguita di nuovo; una sincronizzazione in pausa viene rifiutata finché non è ripresa. force=true fa esportare il design a una sincronizzazione Canva anche quando Canva lo segnala come invariato (rifiutato per una SharePoint: scarica già ogni file modificato).