面向开发者的数字标牌 API

脚本、CI 任务或服务器以服务客户端的身份登录。向令牌端点请求一个 15 分钟有效的访问令牌，然后作为 bearer 发送。以下命令列出项目的屏幕：

# Get a token with a service client's id and secret.
curl -s https://api.screenrig.ai/oauth/token \
  -u "$SCREENRIG_CLIENT_ID:$SCREENRIG_CLIENT_SECRET" \
  -d grant_type=client_credentials

# Put the access_token it returns in $TOKEN, then list the screens.
curl -s https://api.screenrig.ai/api/screens \
  -H "Authorization: Bearer $TOKEN"

没有刷新令牌：令牌过期时重新请求即可。已注册的密钥可以代替密文登录，服务客户端展示了这两种方式。

一份 OpenAPI 契约描述了每一次调用。每个领域都有自己的参考页面，列出每个操作的字段、请求模板及其响应。

API 参考列出了每个分组，包括警报、单点登录和用户配置（SCIM）。

每个调用方都使用自己的会话登录，每个智能体和应用都由人员批准，每个服务客户端都由人员创建。访问令牌放在 Authorization: Bearer 请求头中，有效期 15 分钟。

• 服务器、脚本或 CI 任务使用带密钥或密文的服务客户端，并在令牌过期时请求新令牌。一个客户端最多持有两个密钥和两个密文，所以你可以不停机地轮换，一个组织最多持有 50 个有效的服务客户端。
• 智能体运行 screenrig login，由人员在控制台中批准代码。没有账户的新智能体从 screenrig agent enroll 开始。
• 已连接的应用（如 Claude、ChatGPT 或 Grok）会打开 screenRIG 授权页面。

由人员选择调用方可以做多少、在哪些领域做：屏幕、内容、播放列表、广告、报告和项目。

• 只读可列出和读取。
• 提议还可以上传媒体并提议更改。调用会成功并返回一个审核链接，在有人于控制台中批准更改之前，什么都不会播放。
• 管理还可以更改、发布和支出。

用户可以在控制台的访问页面结束任何会话，其令牌会在几秒内失效。身份验证和服务客户端涵盖密钥、轮换和错误。

每种接口都到达同一个项目，具有相同的项目隔离、速率限制、幂等性和修订检查。远程服务器涵盖 API 风格的调用。涉及移动文件或密文的步骤仍留在 CLI 中。

screenrig CLI 为 shell、cron 任务和终端智能体封装了 API。每条命令都会输出一个 JSON 信封（ok，然后是 data 或 error，附带 request_id），并针对每种结果返回一个退出码，例如 4 表示未找到，5 表示冲突，6 表示修订已过期，7 表示被限速。官方插件已捆绑它。

screenrig screen list --tag Lobby
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000

添加 --idempotency-key 可安全地重试写入。CLI 参考列出了每条命令。

自助终端应用是一个静态网页。发布时，打包器会加入运行时，所以该页面无需构建步骤就能获得 window.screenrig。页面可以等待自己被激活、发送命名事件，并读取一个键值存储，其变化会在几秒内到达运行该应用的每块屏幕。适用于 Android 和 BrightSign 的自助终端软件记录了一个通过聊天构建、点击和改写文字的应用，SDK 参考列出了页面可以调用的所有内容。

screenRIG 在 https://api.screenrig.ai/mcp 运行远程 MCP 服务器。Claude、ChatGPT 或 Grok 通过 OAuth 连接：由人员批准该应用，选择项目以及只读、提议或管理，然后应用会获得用于屏幕、播放列表、媒体、排程、webhook 和报告的工具。官方插件仍是完整的工作流程，因为它会在你的机器上上传文件和打包应用。详情请见 MCP 服务器参考，MCP 服务器对比则把该服务器与其他产品放在一起比较。

想从你正在使用的助手开始？用 ChatGPT 控制电视、Claude、Gemini 或 Grok 展示了各自的安装路径，我的 AI 智能体如何把内容放到电视上？则涵盖了全部。AI 数字标牌列出了示例请求。

智能体的逐步回答。这次运行是真实的：2026年10月26日，在 screenRIG 的预发布环境中。倒计时及其标签是演示内容。

屏幕的修订号就是它的 ETag。把它作为条件发回，只有在此期间没有其他人更改过屏幕时，写入才会生效：

curl -X PATCH "$API/api/screens/$SCREEN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: W/"21"' \
  -d '{"playlist_id": "'"$PLAYLIST"'"}'

第一次，它生效了，屏幕升到了修订 22。用旧修订号再次发送时被拒绝，回答（此处已精简）指出了当前的修订号，客户端可以重新读取并重试：

{"errors": [{"status": 412, "code": "revision_conflict", "current_revision": 22}]}

每个错误都带有稳定的代码、指向其说明的链接，以及提示下一步该怎么做的建议。缺失的 id 会返回 404，并附带如何找到正确 id 的提示。带有幂等键的创建可以安全重试，会话中已经展示过这一点。

触及限制时返回 429 和 Retry-After，CLI 则以退出码 7 退出。以下是对脚本来说重要的几项：

CLI 参考在每条命令旁列出了它所受的限制，套餐限制则见定价。

• 事件流。CLI 和可回放的 REST 流都会传送事件。屏幕离线 60 秒会触发一个事件，恢复时也会触发。重新连接时会从上一个游标继续，不收费。无头数字标牌记录了一条读取该流的流水线。
• 通知。一个组织在其所有项目中最多可设 50 个。当屏幕离线、失去显示、过热、无法存储内容、卡在内容更新上、显示错误而不是播放，或不断崩溃时，会触发邮件或签名 webhook。某个状况默认持续 10 分钟才会触发，所以快速重新连接不会打扰你，而 crashing 则立即触发。webhook 是你运行的 HTTPS 端点，也可以接收原始项目事件。每次投递都有签名，所以请拒绝过旧的时间戳，用恒定时间比较，并按投递或事件 id 去重，因为投递至少一次且无序。请在 10 秒内响应。失败的尝试会以退避方式重试 24 小时，连续 72 小时失败的通知会被停用。

如何验证 webhook？

每次投递都带有 ScreenRig-Signature: t=<unix seconds>,v1=<hex>，其中 v1 是以通知的密文为密钥、对 <t>.<raw body> 计算的 HMAC-SHA256，以及在重试之间保持不变的 ScreenRig-Event-Id。请在解析 JSON 之前，对原始字节进行计算：

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

写入多快能到达屏幕？

在记录的流水线运行中，脚本写入了一行看板数据，事件流传送了整条路径：写入、更改，然后是播放器自己的报告，说明它已把该修订应用到该页面（时间为 UTC，仅保留事件和修订）。

03:43:47.501  kv.updated                 revision 5 written
03:43:47.505  screen.card_data_changed   revision 5
03:43:49.306  screen.card_data_applied   revision 5, page "board"

从接受写入到播放器显示出来，共 1.8 秒。在屏幕显示出结果之前不能继续的任务，可以等待最后一行。无头数字标牌有完整的运行记录。

• MCP 订阅。远程服务器可以让助手订阅事件，因此它可以告诉你某块屏幕已离线。详情请见 MCP 服务器参考。

有十二种播放器可运行 screenRIG 播放列表：Web 播放器、Android 和 Google TV、Amazon Signage Stick、Apple TV、macOS、iPhone 和 iPad、Windows、Linux、Raspberry Pi、LG webOS Signage、Samsung Smart Signage (Tizen) 和 BrightSign。每个播放器都会显示配对码，一次调用即可认领。Apple TV 播放图片、视频、流媒体和卡片。网页和你自己的应用则需要其他播放器。播放器页面有完整的支持表。

screenRIG 有数字标牌 API 吗？

有。REST API 涵盖屏幕、播放列表、媒体、排程、应用、webhook 等，一份 OpenAPI 文件描述了每个操作：版本 0.3.0，3 MB 的文件，包含 562 个路径上的 736 个操作和 1,059 个模式。插件、播放器和控制台使用的是同样的 HTTP 操作。API 参考列出了它们，OpenAPI 契约是单个文件。

screenRIG 是 API 优先的数字标牌软件吗？

是的。API 优先意味着 API 在前，所有客户端都使用它，在这里，控制台、CLI、智能体和播放器都是如此。无头数字标牌展示了在不打开控制台的情况下由流水线运行屏幕。

如何把我自己的数据推送到屏幕？

把它写入卡片的数据或应用的键值存储。键值 webhook 是一个写入单个键的 URL，所以销售终端、电子表格脚本或 cron 任务只需一次 HTTP POST 就能把数据推送到屏幕。订阅了它的应用会在几秒内在每块运行它的屏幕上更新。

我如何得知屏幕离线了？

创建发送邮件或签名 webhook 的通知，或读取可回放的事件流。屏幕在 60 秒后被视为离线，通知默认等待 10 分钟才触发，所以快速重新连接不会打扰你。

触及速率限制时会发生什么？

API 返回 429，其 Retry-After 响应头说明需要等待多久。CLI 以退出码 7 退出并显示 retry_after_seconds。

API 的变化会影响我的脚本吗？

同一主版本内的更改是兼容的：新增端点、可选的请求成员和新的问题代码。会破坏现有调用的更改需要新的主版本，新旧版本至少并行 180 天。

数字标牌 API 免费吗？

screenRIG 免费，屏幕数量不限。付费套餐增加了业务工具、更多成员、可以直接沟通的真人支持、治理功能和合同条款。来自你代码的调用算作智能体请求，每个套餐每月都包含一定数量。请查看定价。

打开 REST API 参考，里面列出了你在这里看到的每一次调用，或者免费开始，让你的智能体去调用。智能体说明了智能体如何自行注册。