API Médias

Liste les médias prêts, les plus récents d’abord, au maximum 1000 par page. folder conserve uniquement les fichiers directement dans un dossier média (son ID), ou root uniquement ceux à la racine de la bibliothèque ; un ID de dossier bien formé qui ne nomme aucun dossier ne liste rien. next_cursor est la position de la dernière ligne retournée tant qu’il reste des lignes ; renvoyez-le comme after, avec les mêmes filtres, pour la page suivante. next_cursor est null à la dernière page.

Générer une image fixe à partir d’une invite, la stocker comme média privé prêt du projet et facturer son utilisation. Le POST répond 202 immédiatement avec Operation, avec ou sans Prefer: respond-async, car un proxy devant l’API abandonne une requête qui n’envoie aucun octet pendant 100 s et une image fixe de haute qualité peut prendre plus de temps.

Interrogez GET /api/operations/{id} jusqu’à ce que Operation soit succeeded, lorsque son result vaut {media_id, usage: {quality, credits, usd}} (MediaGenerationUsage), ou failed, lorsque son error indique le problème. Un refus décidé avant tout travail du fournisseur (payment_required, reseller_generation_limit, rate_limited, not_ready, invalid_request) répond toujours au POST.

Il n'inclut jamais les octets d'image, b64_json, clés d'objet, URL signées, URL du fournisseur, coût du fournisseur, jetons du fournisseur, ni le nom du modèle de déploiement. L'invite est des octets client et n'est pas renvoyée.

Avant que le prompt n’atteigne le fournisseur d’image, le serveur y ajoute des exigences de cadrage fixes : l’œuvre doit remplir le cadre de bord à bord, et aucune télévision, moniteur, écran, afficheur, bordure, cadre, montage, support, mur, pièce, maquette d’appareil, ombre portée ou photographie d’un panneau installé ne peut être représenté, et toute description dans le prompt de l’appelant indiquant où le panneau sera suspendu ou quel appareil l’affichera est traitée comme des métadonnées de placement plutôt que comme sujet.

Les règles décoratives et bordures à l’intérieur du design lui-même restent disponibles. L’invite de l’appelant n’est jamais réécrite ni supprimée et est stockée inchangée. Idempotency-Key rejoue la même Operation, jamais une deuxième tentative facturée. Les clients ne font pas de PUT ni ne valident les octets générés.

La version stockée est un WebP avec perte (qualité 90) à la taille exacte du format avec un bord court de 1080 px (16:9 est 1920x1080, 9:16 1080x1920, 1:1 1080x1080, 4:3 1440x1080, 3:4 1080x1440, 3:2 1620x1080, 2:3 1080x1620) ; la toile du fournisseur est recadrée au centre et rééchantillonnée à cette taille.

Le nom de fichier est distinctif par génération, generated-16x9-1a2b3c4d.webp, avec le suffixe tiré de l’identifiant média. Récupérez les octets avec GET /api/media/{id}/content. Own-gen-then-upload reste valide.

Sur Standard, le solde restant qui ne peut couvrir deux fois le coût fournisseur de l’image fixe, arrondi aux crédits entiers, après le plancher d’introduction (moins 1 000 000 crédits jusqu’au 2027-01-01, puis zéro) renvoie payment_required, sauf SCREENRIG__ENVIRONMENT=development, et l’admission avant l’appel fournisseur exige un solde au-dessus de ce plancher du minimum par qualité : 200 crédits pour faible, 800 pour moyen, 2000 pour élevé.

Les autres forfaits ne sont jamais refusés pour leur solde.

Une organisation facturée par l’entremise d’un revendeur est refusée avec reseller_generation_limit (402) dès que les clients délégués de son revendeur se sont vu facturer la limite mensuelle de génération d’images ($100 au prix de liste tant que le revendeur attend son examen, $1,000 ensuite, comptés par mois UTC), sauf si le crédit propre de l’organisation couvre l’image; une génération déjà admise se termine.

Une configuration vide du fournisseur sélectionné renvoie not_ready. Jeton de projet uniquement. Une seule génération en cours par organisation; tout parallélisme supplémentaire est rate_limited.

Liste chaque dossier média dans le projet, au maximum 1000, ordonnés par nom. Les dossiers organisent la bibliothèque multimédia, et un sélecteur de liste de lecture par :folder lit directement les fichiers dans un dossier. Le parent_id d’un dossier est null à la racine de la bibliothèque.

Construisez l’arbre à partir du parent_id ; le dossier d’un fichier est Media.folder_id. library=true liste à la place les dossiers de la Bibliothèque de l’organisation (en lecture seule ; un sélecteur by:folder peut en nommer un).

Crée un dossier média à la racine de la bibliothèque (parent_id nul ou absent) ou à l’intérieur de parent_id. Les noms sont rognés, contiennent de 1 à 100 caractères Unicode sans contrôles, ne sont ni « . » ni « .. », et peuvent se répéter. Une organisation contient au maximum 1000 dossiers, tous projets confondus (quota_exceeded), imbriqués au maximum à 10 niveaux (invalid_request). Émet media.folder_created.

Renomme un dossier (nom) ou le déplace avec tout son contenu (parent_id, null pour la racine de la bibliothèque). Un dossier ne peut pas être déplacé dans lui-même ou dans un dossier qu’il contient, et le déplacement doit maintenir tous les dossiers dans une profondeur maximale de 10 niveaux (invalid_request). Un changement fait avancer la révision du dossier et émet media.folder_updated ; les mêmes valeurs sont une opération sans effet.

If-Match protège optionnellement la révision.

Supprime un dossier. Rien à l’intérieur n’est supprimé – ses fichiers et dossiers montent dans le parent du dossier supprimé (la racine de la bibliothèque s’il n’en avait pas), chaque fichier et dossier déplacé avance sa révision. Un sélecteur de liste de lecture par :folder qui nomme le dossier supprimé ne correspond plus à rien ; les écrans en lecture abandonnent ce primitif à leur prochaine résolution de sélecteur.

Émet media.folder_deleted. If-Match protège éventuellement la révision.

Déplace des fichiers (media_ids) et des dossiers (folder_ids) dans un dossier (folder_id), ou à la racine de la bibliothèque lorsque folder_id est null, en une seule requête tout ou rien d’au plus 1000 identifiants. Chaque identifiant doit exister (not_found). Un dossier ne peut pas être déplacé dans lui-même ou un dossier à l’intérieur, et le déplacement doit maintenir chaque dossier dans 10 niveaux (invalid_request).

Les éléments déjà dans la destination sont laissés tels quels ; chaque fichier et dossier déplacé avance sa révision. Déplacer des fichiers change ce que les sélecteurs by:folder de leurs anciens et nouveaux dossiers lisent, depuis la résolution du prochain sélecteur de chaque écran ; déplacer un dossier ne change pas les fichiers propres à un dossier. Émet media.moved.

Un déplacement d’identifiant Propose rend chaque fichier déplacé en attente et met en file sa revue média, et les sélecteurs des listes de lecture approuvées le résolvent par le dossier avec lequel il a été approuvé jusqu’à ce qu’une personne approuve le changement (docs/reviews.md).

Aperçu en lecture seule des correspondances d’images ou vidéos prêtes appartenant au projet actuel. Retourne l’ordre des fichiers et la politique normalisée ; la lecture aléatoire est mélangée à chaque nouvelle passe sur le lecteur. Ne fait pas avancer les curseurs, créer des droits de contenu, ni modifier les manifestes. Plus de 1024 correspondances retourne invalid_request.

Définit ou efface l’étiquette ou les étiquettes de l’élément média. Le changement d’étiquette d’une crédential Propose rend l’élément en attente et met en file son examen média ; les sélecteurs des listes de lecture approuvées le résolvent par les étiquettes avec lesquelles il a été approuvé jusqu’à ce qu’une personne approuve le changement (docs/reviews.md). Un patch qui conserve le même ensemble d’étiquettes s’applique et l’élément reste approuvé.

Une personne connectée définit les étiquettes d’un élément média. tags est l’ensemble complet et nouveau, conservé trié : l’étiquette unique d’un élément, lorsqu’il en a une, compte comme une de ses étiquettes et est remplacée par les autres, donc renvoyez-la pour la conserver. Un tableau vide efface toutes les étiquettes, et une étiquette mal formée ou répétée, ou plus de 32, est invalid_request.

C'est la modification de tag que patchMedia effectue sous une autorisation Manage, lors de la session du tableau de bord : la révision des médias avance d'un et media.updated porte la personne comme acteur, que l'ensemble ait changé ou non. Le changement d'une personne est en direct, jamais une revue.

Les médias en attente de révision par une personne (review_state pending, laissés par un téléversement ou changement d’identifiants Propose) sont refusés avec media_pending_review (409) et rien ne change : décidez d’abord de leur révision dans Révisions, ainsi une modification d’étiquette n’approuve jamais une proposition d’agent. Les sélecteurs de playlist par étiquette observent les nouvelles étiquettes à leur prochain rafraîchissement de boucle de playlist.

Le corps n’a pas d’autre membre. If-Match porte la révision du média et est requis (invalid_request s’il est absent, revision_conflict s’il est périmé). Session du tableau de bord uniquement ; les agents changent les balises avec patchMedia. listMedia avec balise trouve l’élément par ses nouvelles balises.

Définit quand un média peut être choisi par les sélecteurs dynamiques (all, tag et folder) qui le jouent, ou supprime la règle avec availability null. La règle est celle de la programmation : from et until (civils, précision à la minute, until exclu), occurrences windows, monthly et dates et dates except, lues dans le fuseau horaire de chaque écran qui résout le sélecteur.

Un fichier hors de sa règle est exclu de la sélection à la prochaine limite de boucle de la liste de lecture, et revient quand la règle est de nouveau satisfaite ; le bord d’une fenêtre est suivi dans la minute qui suit la prochaine boucle du Player. Aucune révision de la liste de lecture ni du manifeste ne change. Les identifiants explicites (sélecteur par id ou ids) ignorent la règle, tout comme tout ce qui n’est pas un sélecteur dynamique.

Un écran hors ligne conserve sa dernière sélection jusqu’à sa reconnexion. Définir la règle que l’élément a déjà ne change rien. Un identifiant Propose ne peut pas la définir (insufficient_access) : le moment où un média est lu revient à une personne ayant l’accès Manage. Un média en attente de révision par une personne est refusé avec media_pending_review.

If-Match porte la révision du média et est obligatoire.

Remplace sur place le fichier d’un élément multimédia prêt par un téléversement déclaré (createMediaUpload) dont les octets ont été écrits, au lieu de l’enregistrer comme nouveau média.

Le média garde son identifiant : chaque liste de lecture et chaque horaire qui le nomme joue donc le nouveau fichier sans être reprogrammé, et les sélecteurs de dossier, d’étiquette et de tous les médias qui le choisissent le jouent à leur prochaine résolution. Le remplacement doit être du même type de fichier (image pour image, vidéo pour vidéo, audio pour audio) ; un autre type donne invalid_request.

Un changement de format d’image est permis : le résultat de l’opération contient une entrée warnings aspect_ratio_changed qui nomme les listes de lecture utilisant l’élément. Toutes les règles de téléversement s’appliquent (limite d’octets vidéo du forfait, limites de dimensions, quota de stockage).

Le fichier en service reste dans l’historique des versions du média (listMediaVersions) et compte dans les octets stockés jusqu’à la suppression de sa version. If-Match, s’il est envoyé, est la révision du média lue par l’appelant (revision_conflict si elle est périmée).

La réponse est l’opération du téléversement, comme pour commitMediaUpload : interrogez getOperation ; le résultat d’une opération réussie est {media_id, id, version, warnings}. Des octets identiques au fichier en service ne remplacent rien et font échouer l’opération avec resource_conflict.

Sous Propose effectif, le remplacement attend plutôt une révision : l’opération réussit avec result.status pending_review et result.review_id, le média continue de jouer son fichier jusqu’à l’approbation d’une personne, et un remplacement plus récent du même média remplace celui qui attend.

Liste les versions d’un élément multimédia, de la plus récente à la plus ancienne, la version en service en premier (current: true). Une version est un fichier qu’a eu l’élément : number est son époque de contenu plus un (1 pour le téléversement, puis un de plus à chaque remplacement, restauration ou changement de synchronisation du média), et ses octets sont conservés jusqu’à la suppression de la version.

Lisez les octets d’une version avec GET /api/media/{id}/content?version=N.

Supprime une version passée : son enregistrement disparaît, ses octets sortent aussitôt des octets stockés du projet, et son objet est retiré après 24 heures, sauf si une autre version ou la version en service détient le même fichier. La version en service ne peut pas être supprimée (resource_conflict), et aucune version ne peut l’être tant qu’un remplacement du média attend une révision.

Une version supprimée ne peut pas être restaurée.

Remet une version passée en service comme nouvelle version, dans l’époque de contenu suivante du média : le média garde son identifiant et la révision avance d’un cran, si bien que chaque liste de lecture et chaque horaire qui le nomme rejoue ce fichier sans être reprogrammé. La version copiée reste dans l’historique et partage ses octets ; la nouvelle version compte comme les autres dans les octets stockés.

La version en service ne peut pas être restaurée (resource_conflict). If-Match, s’il est envoyé, est la révision du média lue par l’appelant. Le corps peut porter une note. Sous Propose effectif, la restauration devient une révision : 202 pending_review, et le média garde son fichier jusqu’à l’approbation d’une personne.

Exporte la version immuable originale appartenant au projet authentifié. Le détenteur du projet est facturé du crédit normal de requête API authentifiée, et les octets de réponse complétés sont enregistrés comme egress project_media_export. L’identifiant média n’est jamais authority : l’identifiant d’un autre projet renvoie not_found.

L’API diffuse depuis un stockage privé et ne publie jamais de clé d’objet, d’URL de stockage ou de GET signé. Le nom du fichier joint est l’identifiant du média plus l’extension canonique pour le type de contenu vérifié. La lecture du contenu n’est jamais refusée en raison du solde.

Une session de tableau de bord affiche les mêmes octets en ligne : les octets complétés sont enregistrés comme egress dashboard_media, et la réponse est privée, no-cache, donc le navigateur garde une copie et la revalide avec If-None-Match. Une réponse de porteur de projet reste privée, no-store.

Applique les mêmes règles de propriété de projet, conditionnelles, de plage et de stockage privé que exportMediaContent sans ouvrir ni transférer la version stockée.

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.

Ajoute un compte qui synchronise en lecture. kind microsoft365 stocke les identifiants de l’application Microsoft Entra propre au projet, de sorte que les synchronisations peuvent lire un dossier SharePoint ou OneDrive Entreprise : config.tenant_id est l’ID de répertoire ou le domaine principal du locataire (common, organizations et consumers sont refusés), config.client_id l’ID d’application de l’application, et secret la valeur de l’un des secrets client de l’application ; l’application exige l’autorisation d’application Microsoft Graph Sites.Selected (accordée sur chaque site) ou Files.Read.All, avec le consentement administrateur.

Au lieu de ces trois paramètres, config.connection_id désigne une connexion Microsoft du projet (createConnection), dans l’un ou l’autre mode, qui se connecte et détient le secret. kind canva ne prend qu’un nom : le compte est pending_consent et la réponse porte authorize_url, un lien à usage unique (valable jusqu’à authorize_expires_at) que la personne titulaire du compte Canva ouvre, connectée à Canva, pour le connecter par l’intégration Canva de screenRIG.

L’autorisation appartient au projet ; ses synchronisations survivent donc à la personne qui a effectué la connexion.

Un serveur sans l’intégration Canva répond 409 canva_not_configured. kind dropbox fonctionne comme canva : le compte est pending_consent et authorize_url est un lien à usage unique que la personne titulaire du compte Dropbox ouvre, connectée à Dropbox, pour autoriser un accès en lecture seule (files.metadata.read, files.content.read, account_info.read, sharing.read).

La connexion passe par l’application Dropbox de screenRIG, ou par l’application Dropbox propre au client lorsque config.app_key la désigne (PKCE, donc sans secret d’application ; l’application doit déclarer https://API_ORIGIN/api/dropbox/callback comme URI de redirection).

Un serveur sans l’application Dropbox de screenRIG répond 409 dropbox_not_configured à un compte dropbox sans app_key. kind google_drive est ready d’emblée et lit les dossiers partagés avec config.service_account_email : le compte de service de screenRIG, ou celui du client lorsque secret est la clé JSON de ce compte de service.

Un dossier partagé avec le compte de service de screenRIG ne se synchronise que si un membre du projet dont le courriel est vérifié l’a partagé ou en est propriétaire. Un serveur sans le compte de service de screenRIG répond 409 google_drive_not_configured à un compte google_drive sans clé. Un secret est scellé au repos et n’est jamais renvoyé ni journalisé. Ajoute media_sync_account.created.

Une nouvelle tentative identique avec la même Idempotency-Key renvoie le même compte (une nouvelle tentative Canva ou Dropbox reçoit un nouveau lien).

Un compte de synchronisation de médias, avec son secret masqué.

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.

Crée un nouveau lien de consentement à usage unique (authorize_url, valide jusqu’à authorize_expires_at) pour un compte Canva ou Dropbox, à envoyer à la personne titulaire de ce compte ; elle l’ouvre en étant connectée à Canva ou à Dropbox et autorise l’accès. Il remplace tout lien précédent.

Un compte connecté reste connecté jusqu’à ce que le nouveau consentement soit terminé ; cela permet donc aussi de renouveler une connexion (état reconnect_required) ou de la déplacer vers un autre compte Canva ou Dropbox. Le lien est un identifiant du consentement : ne l’envoyez qu’à cette personne.

Un serveur sans l’intégration Canva répond 409 canva_not_configured ; un compte Dropbox sans app_key sur un serveur sans l’application Dropbox de screenRIG répond 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.

L’endroit où Canva renvoie la personne après qu’elle a autorisé (ou refusé) l’accès dans un lien de consentement.

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.

L’endroit où Dropbox renvoie la personne après qu’elle a autorisé (ou refusé) l’accès dans un lien de consentement.

Elle ne porte aucun identifiant : le state à usage unique de la requête retrouve le compte Dropbox, ne doit pas être expiré et n’est utilisé qu’une fois, dans la même écriture qui stocke la connexion. screenRIG échange le code (PKCE, avec l’application Dropbox de screenRIG ou l’app_key propre au compte), lit de quel compte Dropbox il s’agit, scelle les jetons et ajoute 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 : lit le design (design est son id ou son adresse canva.com/design/ID/...) via un compte Canva connecté, et enregistre la synchronisation, à exécuter maintenant.

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 que Canva ne montre plus arrête la synchronisation à l’état error (erreur d’exécution design_unavailable) et conserve les médias.

Un design ou une page que le compte ne peut pas voir est 409 media_sync_source_refused. provider dropbox : url est l’adresse du dossier dans Dropbox (https://www.dropbox.com/home/...), un lien de dossier partagé que le compte connecté a ajouté à son Dropbox, ou un chemin commençant par / ; elle est lue une fois par un compte Dropbox connecté et la synchronisation est stockée, à exécuter maintenant.

Les dossiers d’un espace d’équipe sont lus à partir de la racine de l’équipe. Chaque exécution reprend à la position que Dropbox a enregistrée dans le dossier ; seuls les changements sont donc lus.

Un dossier que le compte ne peut pas ouvrir est 409 media_sync_source_refused ; un compte dont Dropbox n’honore plus la connexion est 409 dropbox_reconnect_required. provider google_drive : url est l’adresse Google Drive du dossier (https://drive.google.com/drive/folders/ID) ou son ID, le dossier étant partagé (le rôle Lecteur suffit) avec le service_account_email du compte.

Chaque exécution liste le dossier et compare la somme de contrôle de chaque fichier. Les fichiers Google Docs, Sheets et Slides sont ignorés comme unsupported_type. Un dossier que l’adresse ne permet pas d’ouvrir est 409 media_sync_source_refused.

Lorsqu’il est lu par le compte de service de screenRIG, le dossier doit être partagé par un membre du projet dont le courriel est vérifié, ou lui appartenir (403 media_sync_sharer_not_member), et chaque exécution le revérifie (l’erreur d’exécution sharer_not_member arrête la synchronisation à l’état error). provider sharepoint : lit l’adresse du dossier par le compte (une adresse de site SharePoint comme https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER, ou un lien de partage ; l’application doit pouvoir y accéder : Sites.Selected exige une autorisation sur le site, un lien de partage exige Files.Read.All) et stocke la synchronisation, à exécuter maintenant. folder_id est le dossier de médias où aboutissent les fichiers ; sans lui, la synchronisation en crée un nommé d’après le dossier source.

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.

Une synchronisation de médias, avec le résumé de sa dernière exécution.

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.

Arrête la synchronisation et oublie quel fichier source est devenu quel média. Les médias et leur dossier restent. Ajoute media_sync.deleted. If-Match protège la révision.

Rend la synchronisation exigible maintenant et répond 202 ; un worker l’exécute en 30 secondes environ, et la réponse de GET /api/media-syncs/{id} montre son last_run.

Une synchronisation arrêtée par une erreur redémarre ; une synchronisation en pause est refusée tant qu’elle n’est pas reprise. force=true fait exporter le design par une synchronisation Canva même si Canva le signale inchangé (refusé pour une synchronisation SharePoint : elle télécharge déjà chaque fichier modifié).