媒体 API

列出已准备好的媒体，最新优先，每页最多 1000 条。folder 仅保留直接包含在一个媒体文件夹（其 ID）内的文件，或仅保留库根目录的文件；格式正确但未命名文件夹 ID 不列出任何内容。next_cursor 是最后返回行的位置，若还有更多行；将其作为 after 传回，配合同样的筛选条件，用于下一页。最后一页时 next_cursor 为 null。

根据提示生成一张静态图像，将其存储为项目中已就绪的私有媒体，并对其使用量计费。无论是否带有 Prefer: respond-async，POST 都会立即以 202 返回 Operation，因为 API 前面的代理会丢弃 100 s 内未发送任何字节的请求，而高质量静态图像可能需要更长时间。

轮询 GET /api/operations/{id}，直到 Operation 为 succeeded，此时其 result 为 {media_id, usage: {quality, credits, usd}}（MediaGenerationUsage），或为 failed，此时其 error 为问题所在。在任何供应商工作之前决定的拒绝（payment_required、reseller_generation_limit、rate_limited、not_ready、invalid_request）仍会响应 POST。

绝不包含图像字节、b64_json、对象键、签名 URL、供应商 URL、供应商成本、供应商令牌或部署模型名称。提示为客户字节，不回显。

在提示到达图像供应商之前，服务器会附加固定的构图要求：艺术作品必须填满画框边缘，不得描绘任何电视、显示器、屏幕、显示器边框、框架、边界、安装、支架、墙壁、房间、设备模型、投影阴影或已安装标牌的照片，且调用者提示中描述标牌挂放位置或显示设备的任何文字均视为位置元数据而非主题内容。

设计内部的装饰规则和边框仍然可用。调用者的提示从不被重写或删除，并保持原样存储。Idempotency-Key 会重放相同的 Operation，绝不会进行第二次计费尝试。客户端不会 PUT 或提交生成的字节。

存储的版本为有损 WebP（质量 90），精确长宽比尺寸，短边 1080 px（16:9 为 1920x1080，9:16 为 1080x1920，1:1 为 1080x1080，4:3 为 1440x1080，3:4 为 1080x1440，3:2 为 1620x1080，2:3 为 1080x1620）；供应商画布居中裁剪并重采样至该尺寸。

文件名在每次生成时都独特，格式为 generated-16x9-1a2b3c4d.webp，后缀取自媒体 ID。使用 GET /api/media/{id}/content. 获取字节。Own-gen-then-upload 仍然有效。

在 Standard 上，在入门底线（2027-01-01 前为负 1,000,000 额度，之后为零）之后，余额不足以覆盖静态图像供应商成本的两倍（向上取整为整数额度）时返回 payment_required，SCREENRIG__ENVIRONMENT=development 除外；供应商调用前的准入要求余额高于该底线至少每质量最低值：低质 200 额度，中质 800，高质 2000。

其他计划绝不会因余额而被拒绝。

通过经销商计费的组织，一旦其经销商的委托客户已被计收当月的图像生成上限（经销商等待审核期间按标价 $100，之后 $1,000，按 UTC 月计算），就会被 reseller_generation_limit (402) 拒绝，除非该组织自己的额度可以覆盖该图像；已受理的生成会完成。

所选供应商的配置为空时返回 not_ready。仅限项目 bearer。每个组织同时只能有一个生成任务进行；更多并行会返回 rate_limited。

列出项目中的所有媒体文件夹，最多 1000 个，按名称排序。文件夹组织媒体库，播放列表选择器按文件夹播放直接包含在一个文件夹内的文件。文件夹的 parent_id 在库根目录为 null。

通过 parent_id 构建树；文件的文件夹为 Media.folder_id。library=true 改为列出组织媒体库的文件夹（只读；by:folder 选择器可以指定其中一个）。

在库根目录（parent_id 为空或缺失）或 parent_id 内创建一个媒体文件夹。名称经修剪，包含 1 到 100 个无控制字符的 Unicode 字符，不为“.”或“..”，且可重复。一个组织跨其所有项目最多包含 1000 个文件夹（quota_exceeded），嵌套深度最多 10 层（invalid_request）。发出 media.folder_created。

重命名文件夹（名称）或将其连同内部所有内容移动（parent_id，null 表示库根目录）。文件夹不能移动到自身或其内部的文件夹，且移动后所有文件夹层级不得超过10层（invalid_request）。更改会更新文件夹版本并触发 media.folder_updated；相同值则无操作。

If-Match 可选保护版本。

删除一个文件夹。文件夹内的内容不会被删除——其文件和文件夹上移至被删除文件夹的父级（无父级时为库根目录），每个移动的文件和文件夹都会更新其版本。按文件夹选择器的播放列表如果命名为已删除文件夹，则不匹配任何内容；播放屏幕在下次选择器解析时会丢弃该原始项。

输出 media.folder_deleted。If-Match 可选用于保护修订版本。

将文件（media_ids）和文件夹（folder_ids）移动到一个文件夹（folder_id），或当 folder_id 为 null 时移动到库根目录，一次请求最多 1000 个 ID，全部成功或全部失败。每个 ID 必须存在（not_found）。文件夹不能移动到自身或其内部的文件夹，且移动后所有文件夹层级不得超过 10 层（invalid_request）。

目标中已有的项目保持不变；每个移动的文件和文件夹版本号递增。移动文件改变旧新文件夹的 by:folder 选择器播放内容，基于每屏幕的下一个选择器解析；移动文件夹不改变任何文件夹自身文件。触发 media.moved。

Propose 凭据的移动使每个移动的文件待处理并排队其媒体审核，已批准播放列表的选择器通过其批准的文件夹解析，直到人员批准更改（docs/reviews.md）。

只读预览当前项目拥有的就绪图像或视频匹配。返回文件名排序和标准化策略；播放器每次新循环随机播放。不会推进游标、生成内容授权或更改清单。超过 1024 个匹配返回 invalid_request。

设置或清除媒体项的标签。Propose 凭证更改标签集会使该项待定并排队媒体审核；已批准播放列表的选择器通过其批准时的标签解析该项，直到有人批准更改（docs/reviews.md）。保持相同标签集的补丁生效且该项保持批准状态。

已登录人员设置媒体项标签。tags 是完整的新集合，保持排序：单标签项计为其标签之一，替换其余标签，故需再次发送以保留。空数组清除所有标签，格式错误、重复标签或超过 32 个返回 invalid_request。

是 Manage 凭证下 patchMedia 的标签变更：媒体版本号加一，media.updated 记录操作者，无论集合是否变更。用户变更为实时，非审核。

等待人员审核的媒体（review_state 待处理，由 Propose 凭证上传或更改）被拒绝，返回 media_pending_review（409），且无任何更改：请先在审核中决定其审核结果，标签编辑永远不会批准代理提议。标签选择器在下一次播放列表循环刷新时观察新标签。

主体无其他成员。If-Match 携带媒体版本，必需（缺失时为 invalid_request，版本过旧时为 revision_conflict）。仅限仪表板会话；代理用 patchMedia 更改标签。listMedia 通过标签查找项目。

设置媒体项目何时可被播放它的动态选择器（all、tag 和 folder）选取，或用 availability null 清除规则。规则与排程相同：from 和 until（民用时间，精确到分钟，until 不含）、windows、monthly 和 dates 的重复，以及 except 日期，按解析该选择器的每个屏幕的时区读取。

不符合规则的文件会在下一个播放列表循环边界从选择中排除，规则重新生效时再回来；窗口边缘在播放器下一次循环后一分钟内跟进。播放列表和清单的修订版都不会改变。显式 ID（按 id 或 ids 的选择器）会忽略该规则，所有非动态选择器的内容也一样。

离线的屏幕会保持其上次的选择，直到重新连接。设置该项目已有的规则不会产生任何更改。Propose 凭据无法设置它（insufficient_access）：媒体何时播放由具有 Manage 访问权限的成员决定。等待成员审核的媒体会被拒绝，返回 media_pending_review。

If-Match 携带媒体修订版，且为必填。

用已声明（createMediaUpload）且字节已写入的上传，就地替换已就绪媒体项目的文件，而不是将其提交为新媒体。

媒体保留其 id，因此所有引用它的播放列表和计划无需重新安排即可播放新文件，选中它的文件夹、标签和全部媒体选择器会在下次解析时播放新文件。替换文件必须是同一类型（图像换图像、视频换视频、音频换音频）；其他类型会返回 invalid_request。

允许更改宽高比：操作结果会带有 warnings 条目 aspect_ratio_changed，列出使用该项目的播放列表。所有上传规则均适用（套餐的视频字节上限、尺寸上限、存储配额）。

使用中的文件会保留在媒体的版本历史（listMediaVersions）中，并计入已存储字节，直到其版本被删除。如发送 If-Match，则为调用方读取到的媒体修订号（过期时返回 revision_conflict）。

响应是该上传的操作，与 commitMediaUpload 相同：轮询 getOperation；成功操作的结果为 {media_id, id, version, warnings}。与使用中文件字节相同的上传不会替换任何内容，操作会以 resource_conflict 失败。

在生效的 Propose 下，替换会改为等待审核：操作成功并返回 result.status pending_review 和 result.review_id，在有人批准之前媒体继续播放其原文件，同一媒体较新的替换会取代正在等待的那个。

按从新到旧列出媒体项目的版本，使用中的版本排在最前（current: true）。版本即该项目曾有的文件：number 为其内容纪元加一（上传为 1，每次替换、恢复或媒体同步变更再加一），其字节会一直保留，直到该版本被删除。

可通过 GET /api/media/{id}/content?version=N 读取某个版本的字节。

删除一个过去的版本：其记录被移除，其字节立即从项目的已存储字节中扣除，其对象在 24 小时后删除，除非另一个版本或当前使用中的版本持有同一文件。使用中的版本无法删除（resource_conflict），媒体的替换等待审核期间，任何版本都不能删除。

已删除的版本无法恢复。

将一个过去的版本作为新版本重新投入使用，位于媒体的下一个内容纪元：媒体保留其 id，修订号加一，因此所有引用它的播放列表和计划无需重新安排即可再次播放该文件。被复制的版本仍保留在历史中并共用其字节；新版本与其他版本一样计入已存储字节。

使用中的版本无法恢复（resource_conflict）。如发送 If-Match，则为调用方读取到的媒体修订号。请求体可附带备注。在生效的 Propose 下，恢复会变成审核：202 pending_review，在有人批准之前，媒体保留其原文件。

导出由认证项目拥有的原始不可变版本。项目持有者被收取正常认证 API 请求额度，完成响应字节记录为 project_media_export 出站流量。媒体标识符绝不为 authority：其他项目标识符返回 not_found。

API 从私有存储流式传输，且从不公开对象密钥、存储 URL 或签名的 GET。附件文件名为媒体标识符加上经过验证内容类型的规范扩展名。读取内容从不因余额被拒绝。

控制台会话内联查看相同字节：完成的字节计入 dashboard_media 出站，响应为 private, no-cache，浏览器保存一份副本并用 If-None-Match 重新验证。项目持有者响应为 private, no-store。

应用与 exportMediaContent 相同的项目所有权、条件、范围和私有存储规则，但不打开或传输存储的版本。

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.

添加一个通过读取来同步的账号。kind microsoft365 存储项目自己的 Microsoft Entra 应用的凭据，使同步可以读取 SharePoint 或 OneDrive 工作文件夹：config.tenant_id 是租户的目录 ID 或主域名（common、organizations 和 consumers 会被拒绝），config.client_id 是应用的应用程序 ID，secret 是应用某个客户端密钥的值；该应用需要经管理员同意的 Microsoft Graph 应用程序权限 Sites.Selected（在每个站点上授予）或 Files.Read.All。

可以不用这三项，改用 config.connection_id 指定项目的 Microsoft 连接（createConnection，两种模式均可），由它登录并保存密钥。kind canva 只接受名称：账号处于 pending_consent，响应带有 authorize_url（有效期至 authorize_expires_at 的一次性链接），由 Canva 账号的所有者在登录 Canva 后打开，通过 screenRIG 的 Canva 集成连接。

该授权属于项目，因此其同步在连接它的人离开后仍会继续。

没有 Canva 集成的服务器会返回 409 canva_not_configured。kind dropbox 的工作方式与 canva 相同：账户处于 pending_consent 状态，authorize_url 是一次性链接，由 Dropbox 账户的所有者在登录 Dropbox 后打开，以允许只读访问（files.metadata.read、files.content.read、account_info.read、sharing.read）。

它通过 screenRIG 的 Dropbox 应用进行；当 config.app_key 指定了客户自己的 Dropbox 应用时，则通过该应用进行（使用 PKCE，因此没有 app secret；该应用必须将 https://API_ORIGIN/api/dropbox/callback 列为重定向 URI）。

没有 screenRIG Dropbox 应用的服务器，会对没有 app_key 的 dropbox 账户返回 409 dropbox_not_configured。kind google_drive 立即处于 ready 状态，读取与 config.service_account_email 共享的文件夹：即 screenRIG 的服务账号，或当 secret 是该服务账号的 JSON 密钥时，客户自己的服务账号。

与 screenRIG 的服务账号共享的文件夹，仅当共享者或所有者是邮箱已验证的项目成员时才会同步。没有 screenRIG 服务账号的服务器，会对不带密钥的 google_drive 账户返回 409 google_drive_not_configured。密钥在存储时即加密封存，绝不会返回，也不会写入日志。追加 media_sync_account.created。

使用相同 Idempotency-Key 的完全相同的重试会返回同一个账户（Canva 或 Dropbox 的重试会得到新的链接）。

一个媒体同步账户，密钥已被遮蔽。

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.

为 Canva 或 Dropbox 账户生成新的一次性授权链接（authorize_url，有效期至 authorize_expires_at），发送给该账户的所有者；对方登录 Canva 或 Dropbox 后打开它并允许访问。它会取代之前的所有链接。

已连接的账户在新的授权完成之前保持连接，因此这也可用于续期连接（状态为 reconnect_required），或把它改连到另一个 Canva 或 Dropbox 账户。该链接是授权的凭据：只发送给那个人。

没有 Canva 集成的服务器会返回 409 canva_not_configured；在没有 screenRIG Dropbox 应用的服务器上，没有 app_key 的 Dropbox 账户会返回 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.

用户在授权链接中允许（或拒绝）访问后，Canva 将其重定向到的位置。

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.

用户在授权链接中允许（或拒绝）访问后，Dropbox 将其重定向到的位置。

它不携带任何凭据：查询中的一次性 state 用于找到 Dropbox 账户，必须未过期，并在保存连接的同一次写入中仅使用一次。screenRIG 兑换授权码（PKCE，使用 screenRIG 的 Dropbox 应用或该账户自己的 app_key），读取该 Dropbox 账户属于谁，加密封存令牌，并追加 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：通过已连接的 Canva 账户读取设计（design 是其 id 或 canva.com/design/ID/... 地址），并保存该同步，立即到期。

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.

Canva 不再显示的设计会使同步停在 error 状态（运行错误 design_unavailable），并保留媒体。

账户看不到的设计或页面会返回 409 media_sync_source_refused。provider dropbox：url 是形如 https://www.dropbox.com/home/... 的 Dropbox 文件夹地址、已连接账户添加到其 Dropbox 的共享文件夹链接，或以 / 开头的路径；它通过已连接的 Dropbox 账户读取一次，并保存该同步，立即到期。

团队空间中的文件夹从团队根目录读取。每次运行都从 Dropbox 在该文件夹中保存的位置继续，因此只读取变更。

账户无法打开的文件夹会返回 409 media_sync_source_refused；Dropbox 不再认可其连接的账户会返回 409 dropbox_reconnect_required。provider google_drive：url 是形如 https://drive.google.com/drive/folders/ID 的 Google Drive 文件夹地址或其 id，并已与该账户的 service_account_email 共享（Viewer 权限即可）。

每次运行都会列出文件夹，并比较每个文件的校验和。Google Docs、Sheets 和 Slides 文件会因 unsupported_type 被跳过。地址无法打开的文件夹会返回 409 media_sync_source_refused。

通过 screenRIG 的服务账号读取时，文件夹必须由邮箱已验证的项目成员共享或拥有（403 media_sync_sharer_not_member），并且每次运行都会再次检查（运行错误 sharer_not_member 会使同步停在 error 状态）。provider sharepoint：通过该账户读取文件夹的地址（形如 https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER 的 SharePoint 站点地址，或共享链接；应用必须能看到它：Sites.Selected 需要在站点上授予权限，共享链接需要 Files.Read.All），并保存该同步，立即到期。folder_id 是文件落入的媒体文件夹；省略时，同步会创建一个以来源文件夹命名的媒体文件夹。

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.

一个媒体同步及其最近一次运行的摘要。

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.

停止同步，并忘记哪个源文件对应哪个媒体。媒体及其文件夹保持不变。追加 media_sync.deleted。If-Match 用于保护修订号。

使同步立即到期并返回 202；工作进程会在约 30 秒内运行它，GET /api/media-syncs/{id} 的应答会显示其 last_run。

因错误而停止的同步会再次运行；已暂停的同步在恢复前会被拒绝。force=true 会使 Canva 同步即使在 Canva 报告设计未变化时也导出该设计（SharePoint 同步会被拒绝：它本来就会下载每个变更的文件）。