API de Medios

Lista multimedia listo, las más nuevas primero, máximo 1000 por página. folder mantiene solo los archivos directamente dentro de una carpeta multimedia (su ID), o con root solo los de la raíz de la biblioteca; un ID de carpeta bien formado que no nombra ninguna carpeta no lista nada. next_cursor es la posición de la última fila devuelta mientras queden más filas; páselo como after, con los mismos filtros, para la siguiente página. next_cursor es nulo en la última página.

Generar una imagen fija a partir de un prompt, almacenarla como medio privado listo del proyecto y facturar su uso. El POST responde 202 de inmediato con Operation, con o sin Prefer: respond-async, porque un proxy situado delante de la API descarta una solicitud que no envía ningún byte durante 100 s y una imagen fija de alta calidad puede tardar más.

Consulte GET /api/operations/{id} hasta que Operation sea succeeded, cuando su result es {media_id, usage: {quality, credits, usd}} (MediaGenerationUsage), o failed, cuando su error es el problema. Un rechazo decidido antes de cualquier trabajo del proveedor (payment_required, reseller_generation_limit, rate_limited, not_ready, invalid_request) aún responde al POST.

Nunca incluye bytes de imagen, b64_json, claves de objeto, URLs firmadas, URLs del proveedor, costo del proveedor, tokens del proveedor ni el nombre del modelo de despliegue. El prompt son bytes del cliente y no se repite.

Antes de que la indicación llegue al proveedor de imágenes, el servidor añade requisitos fijos de encuadre: la obra debe llenar el marco de borde a borde, y no se puede mostrar ningún televisor, monitor, pantalla, panel, marco, borde, montaje, soporte, pared, habitación, maqueta de dispositivo, sombra o fotografía de un letrero instalado, y cualquier texto en la indicación del llamante que describa dónde colgará el letrero o qué dispositivo lo mostrará se trata como metadatos de ubicación y no como tema.

Las reglas decorativas y los bordes dentro del propio diseño permanecen disponibles. El prompt del llamador nunca se reescribe ni se elimina y se almacena sin cambios. Idempotency-Key reproduce la misma Operation, nunca un segundo intento facturado. Los clientes no hacen PUT ni confirman los bytes generados.

La versión almacenada es WebP con pérdida (calidad 90) en el tamaño exacto de aspecto con un borde corto de 1080 px (16:9 es 1920x1080, 9:16 1080x1920, 1:1 1080x1080, 4:3 1440x1080, 3:4 1080x1440, 3:2 1620x1080, 2:3 1080x1620); el lienzo del proveedor se recorta y remuestrea centrado a ese tamaño.

El nombre de archivo es distintivo por generación, generado-16x9-1a2b3c4d.webp, con el sufijo tomado del id del medio. Obtenga los bytes con GET /api/media/{id}/content. Own-gen-then-upload sigue siendo válido.

En Standard, el saldo restante que no puede cubrir el doble del costo del proveedor de la imagen fija, redondeado a créditos enteros, después del piso de introducción (negativo 1,000,000 créditos hasta 2027-01-01, luego cero) devuelve payment_required, excepto SCREENRIG__ENVIRONMENT=development, y la admisión antes de la llamada al proveedor requiere un saldo por encima de ese piso por el mínimo por calidad: 200 créditos para baja, 800 para media, 2000 para alta.

Los demás planes nunca se rechazan por su saldo.

Una organización facturada a través de un revendedor es rechazada con reseller_generation_limit (402) en cuanto a los clientes delegados de su revendedor se les ha facturado el límite mensual de generación de imágenes ($100 a precio de lista mientras el revendedor espera revisión, $1,000 después, contado por mes UTC), salvo que el crédito propio de la organización cubra la imagen; una generación ya admitida termina.

Una configuración vacía del proveedor seleccionado devuelve not_ready. Solo con token de proyecto. Una sola generación en curso por organización; más paralelismo es rate_limited.

Lista todas las carpetas multimedia en el proyecto, máximo 1000, ordenadas por nombre. Las carpetas organizan la biblioteca multimedia, y un selector de playlist por:folder reproduce los archivos directamente dentro de una carpeta. El parent_id de una carpeta es nulo en la raíz de la biblioteca.

Construya el árbol desde parent_id; la carpeta de un archivo es Media.folder_id. library=true enumera en su lugar las carpetas de la Biblioteca de la organización (solo lectura; un selector by:folder puede nombrar una).

Crea una carpeta de medios en la raíz de la biblioteca (parent_id nulo o ausente) o dentro de parent_id. Los nombres se recortan, tienen de 1 a 100 caracteres Unicode sin controles, no son "." ni "..", y pueden repetirse. Una organización tiene como máximo 1000 carpetas en todos sus proyectos (quota_exceeded) anidadas a lo sumo 10 niveles (invalid_request). Emite media.folder_created.

Renombra una carpeta (nombre) o la mueve con todo su contenido (parent_id, null para la raíz de la biblioteca). Una carpeta no puede moverse dentro de sí misma ni dentro de una carpeta contenida en ella, y el movimiento debe mantener todas las carpetas dentro de 10 niveles (invalid_request). Un cambio avanza la revisión de la carpeta y emite media.folder_updated; los mismos valores no tienen efecto.

If-Match protege opcionalmente la revisión.

Elimina una carpeta. Nada dentro se elimina: sus archivos y carpetas se mueven al padre de la carpeta eliminada (la raíz de la biblioteca si no tenía padre), cada archivo y carpeta movidos avanza su revisión. Un selector de lista de reproducción por:folder que nombre la carpeta eliminada ya no coincide con nada; las pantallas en reproducción eliminan ese primitivo en su próxima resolución de selector.

Emite media.folder_deleted. If-Match protege opcionalmente la revisión.

Mueve archivos (media_ids) y carpetas (folder_ids) a una carpeta (folder_id), o a la raíz de la biblioteca cuando folder_id es nulo, en una sola solicitud todo o nada de hasta 1000 IDs. Cada ID debe existir (not_found). Una carpeta no puede moverse dentro de sí misma ni dentro de una carpeta contenida en ella, y el movimiento debe mantener cada carpeta dentro de 10 niveles (invalid_request).

Los elementos ya en el destino se dejan tal cual; cada archivo y carpeta movidos avanza su revisión. Mover archivos cambia lo que los selectores by:folder de sus carpetas vieja y nueva reproducen, desde la resolución del siguiente selector de cada pantalla; mover una carpeta no cambia los archivos propios de ninguna carpeta. Emite media.moved.

El movimiento de una credencial Propose hace que cada archivo movido quede pendiente y pone en cola su revisión de medios, y los selectores de listas de reproducción aprobadas lo resuelven por la carpeta con la que fue aprobado hasta que una persona aprueba el cambio (docs/reviews.md).

Vista previa solo lectura de coincidencias actuales de imagen o video propiedad del proyecto. Devuelve orden de archivo y política normalizada; la reproducción aleatoria se baraja en cada nuevo ciclo en el Player. No avanza cursores, concede contenido ni altera manifiestos. Más de 1024 coincidencias devuelve invalid_request.

Establece o borra la etiqueta o etiquetas del elemento multimedia. Un cambio de conjunto de etiquetas en una credencial Propose hace que el elemento quede pendiente y encola su revisión de medios; los selectores de listas de reproducción aprobadas lo resuelven por las etiquetas con las que fue aprobado hasta que una persona aprueba el cambio (docs/reviews.md). Un parche que mantiene el mismo conjunto de etiquetas se aplica y el elemento permanece aprobado.

Una persona conectada establece las etiquetas de un ítem multimedia. tags es el conjunto nuevo completo, mantenido ordenado: la etiqueta única de un ítem, cuando tiene una, cuenta como una de sus etiquetas y se reemplaza con las demás, así que envíela de nuevo para conservarla. Un arreglo vacío borra todas las etiquetas, y una etiqueta mal formada o repetida, o más de 32, es invalid_request.

Es el cambio de etiqueta que patchMedia hace bajo una credencial Manage, en la sesión del panel: la revisión del media avanza en uno y media.updated lleva a la persona como actor, haya o no cambiado el conjunto. El cambio de una persona es en vivo, nunca una revisión.

Los contenidos multimedia que esperan la revisión de una persona (review_state pendientes, dejados por una carga o cambio con credenciales Propose) son rechazados con media_pending_review (409) y no cambia nada: decida su revisión primero en Revisiones, para que una edición de etiqueta nunca apruebe una propuesta de agente. Los selectores de listas de reproducción por etiqueta observan las nuevas etiquetas en su siguiente actualización del ciclo de lista de reproducción.

El cuerpo no tiene otro miembro. If-Match lleva la revisión del medio y es obligatorio (invalid_request cuando falta, revision_conflict cuando está obsoleta). Solo sesión del panel; los agentes cambian etiquetas con patchMedia. listMedia con etiqueta encuentra el elemento por sus nuevas etiquetas.

Define cuándo un medio puede ser elegido por los selectores dinámicos (all, tag y folder) que lo reproducen, o borra la regla con availability null. La regla es la del horario: from y until (civiles, precisión de minuto, until exclusivo), repeticiones de windows, monthly y dates, y fechas except, leídas en la zona horaria de cada pantalla que resuelve el selector.

Un archivo fuera de su regla queda excluido de la selección en el siguiente límite del bucle de la lista de reproducción y vuelve cuando la regla rige de nuevo; el borde de una ventana se sigue en el minuto posterior al siguiente bucle del Player. No cambia ninguna revisión de la lista de reproducción ni del manifiesto. Los ids explícitos (selector por id o ids) ignoran la regla, igual que todo lo que no es un selector dinámico.

Una pantalla sin conexión conserva su última selección hasta que se reconecta. Definir la regla que el elemento ya tiene no cambia nada. Una credencial Propose no puede definirla (insufficient_access): decidir cuándo se reproduce un medio corresponde a una persona con acceso Manage. Un medio en espera de revisión de una persona se rechaza con media_pending_review.

If-Match lleva la revisión del medio y es obligatorio.

Reemplaza en el sitio el archivo de un elemento multimedia listo por una carga declarada (createMediaUpload) cuyos bytes se escribieron, en lugar de confirmarla como medio nuevo.

El medio conserva su id, por lo que cada lista de reproducción y cada horario que lo nombra reproduce el archivo nuevo sin reprogramarse, y los selectores de carpeta, etiqueta y todos los medios que lo eligen lo reproducen en su siguiente resolución. El reemplazo debe ser del mismo tipo de archivo (imagen por imagen, vídeo por vídeo, audio por audio); otro tipo da invalid_request.

Se permite un cambio de relación de aspecto: el resultado de la operación incluye una entrada warnings aspect_ratio_changed que nombra las listas de reproducción que usan el elemento. Se aplican todas las reglas de carga (el límite de bytes de vídeo del plan, los límites de dimensiones y la cuota de almacenamiento).

El archivo en servicio permanece en el historial de versiones del medio (listMediaVersions) y cuenta en los bytes almacenados hasta que se elimina su versión. If-Match, si se envía, es la revisión del medio que leyó quien llama (revision_conflict si está obsoleta).

La respuesta es la operación de la carga, como en commitMediaUpload: consulte getOperation; el resultado de una operación correcta es {media_id, id, version, warnings}. Unos bytes idénticos al archivo en servicio no reemplazan nada y hacen fallar la operación con resource_conflict.

Con Propose efectivo, el reemplazo espera en cambio una revisión: la operación termina con éxito con result.status pending_review y result.review_id, el medio sigue reproduciendo su archivo hasta que una persona lo apruebe, y un reemplazo más reciente del mismo medio sustituye al que espera.

Lista las versiones de un elemento multimedia, de la más reciente a la más antigua, con la versión en servicio primero (current: true). Una versión es un archivo que tuvo el elemento: number es su época de contenido más uno (1 para la carga, uno más por cada reemplazo, restauración o cambio de sincronización del medio), y sus bytes se conservan hasta que se elimina la versión.

Lea los bytes de una versión con GET /api/media/{id}/content?version=N.

Elimina una versión anterior: su registro desaparece, sus bytes dejan de contar de inmediato en los bytes almacenados del proyecto y su objeto se retira pasadas 24 horas, salvo que otra versión o la versión en servicio contenga el mismo archivo. La versión en servicio no se puede eliminar (resource_conflict), y ninguna versión se puede eliminar mientras un reemplazo del medio espera revisión.

Una versión eliminada no se puede restaurar.

Vuelve a poner en servicio una versión anterior como versión nueva, en la siguiente época de contenido del medio: el medio conserva su id y la revisión avanza una unidad, de modo que cada lista de reproducción y cada horario que lo nombra vuelve a reproducir ese archivo sin reprogramarse. La versión copiada permanece en el historial y comparte sus bytes; la versión nueva cuenta en los bytes almacenados como cualquier otra.

La versión en servicio no se puede restaurar (resource_conflict). If-Match, si se envía, es la revisión del medio que leyó quien llama. El cuerpo puede incluir una nota. Con Propose efectivo, la restauración se convierte en una revisión: 202 pending_review, y el medio conserva su archivo hasta que una persona lo apruebe.

Exporta la versión inmutable original propiedad del proyecto autenticado. El portador del proyecto paga el crédito normal de solicitud API autenticada, y los bytes de respuesta completados se registran como egreso project_media_export. El identificador de medios nunca es authority: el identificador de otro proyecto devuelve not_found.

La API transmite desde almacenamiento privado y nunca publica una clave de objeto, URL de almacenamiento ni GET firmado. El nombre del archivo adjunto es el identificador multimedia más la extensión canónica para el tipo de contenido verificado. Leer contenido nunca se rechaza por el saldo.

Una sesión del panel ve los mismos bytes en línea: los bytes completados se registran como egreso dashboard_media, y la respuesta es privada, no-cache para que el navegador mantenga una copia y la revalide con If-None-Match. La respuesta de un portador de proyecto permanece privada, no-store.

Aplica las mismas reglas de propiedad del proyecto, condicionales, rango y almacenamiento privado que exportMediaContent sin abrir ni transferir la versión almacenada.

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.

Añade una cuenta que sincroniza leyendo. kind microsoft365 almacena las credenciales de la propia aplicación de Microsoft Entra del proyecto, para que las sincronizaciones puedan leer una carpeta de SharePoint o de OneDrive para la empresa: config.tenant_id es el ID de directorio o el dominio principal del tenant (common, organizations y consumers se rechazan), config.client_id el ID de aplicación de la aplicación, y secret el valor de uno de los secretos de cliente de la aplicación; la aplicación necesita el permiso de aplicación de Microsoft Graph Sites.Selected (concedido en cada sitio) o Files.Read.All, con consentimiento del administrador.

En lugar de esos tres, config.connection_id nombra una conexión de Microsoft del proyecto (createConnection), en cualquiera de los dos modos, que inicia sesión y guarda el secreto. kind canva solo toma un nombre: la cuenta queda en pending_consent y la respuesta lleva authorize_url, un enlace de un solo uso (válido hasta authorize_expires_at) que abre la persona titular de la cuenta de Canva, con la sesión iniciada en Canva, para conectarla mediante la integración de Canva de screenRIG.

La concesión pertenece al proyecto, así que sus sincronizaciones sobreviven a la persona que la conectó.

Un servidor sin la integración de Canva responde 409 canva_not_configured. kind dropbox funciona como canva: la cuenta queda en pending_consent y authorize_url es un enlace de un solo uso que abre la persona titular de la cuenta de Dropbox, con la sesión iniciada en Dropbox, para permitir el acceso de solo lectura (files.metadata.read, files.content.read, account_info.read, sharing.read).

Se hace a través de la aplicación de Dropbox de screenRIG o, cuando config.app_key la nombra, a través de la propia aplicación de Dropbox del cliente (PKCE, así que no hay secreto de la aplicación; la aplicación debe incluir https://API_ORIGIN/api/dropbox/callback como URI de redirección).

Un servidor sin la aplicación de Dropbox de screenRIG responde 409 dropbox_not_configured a una cuenta dropbox sin app_key. kind google_drive queda en ready de inmediato y lee las carpetas compartidas con config.service_account_email: la cuenta de servicio de screenRIG, o la del propio cliente cuando secret es la clave JSON de esa cuenta de servicio.

Una carpeta compartida con la cuenta de servicio de screenRIG solo se sincroniza cuando un miembro del proyecto con un correo electrónico verificado la compartió o es su propietario. Un servidor sin la cuenta de servicio de screenRIG responde 409 google_drive_not_configured a una cuenta google_drive sin clave. Un secreto se sella en reposo y nunca se devuelve ni se registra. Añade media_sync_account.created.

Un reintento exacto con la misma Idempotency-Key devuelve la misma cuenta (un reintento de Canva o de Dropbox recibe un enlace nuevo).

Una cuenta de sincronización de medios, con su secreto enmascarado.

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.

Genera un nuevo enlace de consentimiento de un solo uso (authorize_url, válido hasta authorize_expires_at) para una cuenta de Canva o de Dropbox, para enviarlo a la persona titular de esa cuenta; la persona lo abre con la sesión iniciada en Canva o en Dropbox y permite el acceso. Sustituye cualquier enlace anterior.

Una cuenta conectada sigue conectada hasta que se completa el nuevo consentimiento, así que esto también renueva una conexión (estado reconnect_required) o la mueve a otra cuenta de Canva o de Dropbox. El enlace es una credencial del consentimiento: envíelo solo a esa persona.

Un servidor sin la integración de Canva responde 409 canva_not_configured; una cuenta de Dropbox sin app_key en un servidor sin la aplicación de Dropbox de screenRIG responde 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.

Adónde envía Canva a la persona después de que permita (o rechace) el acceso en un enlace de consentimiento.

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.

Adónde envía Dropbox a la persona después de que permita (o rechace) el acceso en un enlace de consentimiento.

No lleva ninguna credencial: el state de un solo uso de la consulta localiza la cuenta de Dropbox, no debe haber caducado y se usa una sola vez, en la misma escritura que guarda la conexión. screenRIG canjea el código (PKCE, con la aplicación de Dropbox de screenRIG o con el app_key propio de la cuenta), lee de quién es la cuenta de Dropbox, sella los tokens y añade 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: lee el diseño (design es su id o su dirección canva.com/design/ID/...) a través de una cuenta de Canva conectada y guarda la sincronización, que vence ahora.

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 diseño que Canva ya no muestra detiene la sincronización en el estado error (error de ejecución design_unavailable) y conserva los medios.

Un diseño o una página que la cuenta no puede ver da 409 media_sync_source_refused. provider dropbox: url es la dirección de la carpeta en Dropbox (https://www.dropbox.com/home/...), un enlace de carpeta compartida que la cuenta conectada ha agregado a su Dropbox, o una ruta que empieza con /; se lee una vez a través de una cuenta de Dropbox conectada y se guarda la sincronización, que vence ahora.

Las carpetas de un espacio de equipo se leen desde la raíz del equipo. Cada ejecución continúa desde la posición guardada de Dropbox en la carpeta, de modo que solo se leen los cambios.

Una carpeta que la cuenta no puede abrir da 409 media_sync_source_refused; una cuenta cuya conexión Dropbox ya no acepta da 409 dropbox_reconnect_required. provider google_drive: url es la dirección de la carpeta en Google Drive (https://drive.google.com/drive/folders/ID) o su id, compartida (basta con el rol Lector) con el service_account_email de la cuenta.

Cada ejecución lista la carpeta y compara la suma de verificación de cada archivo. Los archivos de Google Docs, Sheets y Slides se omiten como unsupported_type. Una carpeta que la dirección no puede abrir da 409 media_sync_source_refused.

Con la cuenta de servicio de screenRIG, la carpeta debe haber sido compartida por un miembro del proyecto con un correo electrónico verificado o ser de su propiedad (403 media_sync_sharer_not_member), y cada ejecución lo comprueba de nuevo (el error de ejecución sharer_not_member detiene la sincronización en el estado error). provider sharepoint: lee la dirección de la carpeta a través de la cuenta (una dirección de sitio de SharePoint como https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER, o un enlace para compartir; la aplicación debe poder verla: Sites.Selected necesita una concesión en el sitio, un enlace para compartir necesita Files.Read.All) y guarda la sincronización, que vence ahora. folder_id es la carpeta de medios en la que se guardan los archivos; sin él, la sincronización crea una con el nombre de la carpeta de origen.

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 sincronización de medios, con el resumen de su última ejecución.

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.

Detiene la sincronización y olvida qué archivo de origen se convirtió en qué medio. Los medios y su carpeta permanecen. Agrega media_sync.deleted. If-Match protege la revisión.

Hace que la sincronización venza ahora y responde 202; un worker la ejecuta en unos 30 segundos y la respuesta de GET /api/media-syncs/{id} muestra su last_run.

Una sincronización detenida por un error vuelve a ejecutarse; una sincronización en pausa se rechaza hasta que se reanude. force=true hace que una sincronización de Canva exporte el diseño aunque Canva lo indique como sin cambios (se rechaza para una de SharePoint: ya descarga cada archivo modificado).