screenRIG
登录开始使用

API 参考

播放与报告 API

运行时清单、报告和事件

HTTP 参考。 由后端契约生成。浏览以下端点或下载 OpenAPI。

OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览

此分组有 24 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。

用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。

运行时清单、报告和事件

POST/screen/browser-provisioning/exchanges

交换浏览器配置

仅限浏览器同源交换。原子绑定一次性令牌到 exchange_id，并仅设置普通的仅限主机 HttpOnly Secure SameSite=Strict 配对设备 Cookie。Android 和 Qt 从不使用此授权。

身份验证
无
请求主体
BrowserProvisioningExchange
操作 ID
exchangeBrowserProvisioning

请求主体字段

字段描述
provisioning_token（必填，字符串）模式："^[A-Za-z0-9_-]{43}$"
exchange_id（必填，字符串）模式："^xchg_[A-Za-z0-9_-]{43}$"
请求模板和响应
shell · 请求模板
curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/browser-provisioning/exchanges'

响应

状态含义正文和头部
201已配对设备的 cookie 在正文中未包含运行时 cookie 或凭证即已发出。BrowserProvisioningCompletion（application/json）；头部：Cache-Control，Referrer-Policy，RateLimit-Policy，RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
404

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
410

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
500

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
GET/screen/chrome

获取运行时 Chrome

当前运行时会话的舞台界面。不是运行时清单的一部分。认证是相同的运行时 cookie 或 ScreenRig-Session，如 GET /screen/manifest.。Cache-Control 是私有的，不存储。横幅始终为 null。

身份验证
runtimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
getRuntimeChrome
请求模板和响应
shell · 请求模板
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/chrome'

响应

状态含义正文和头部
200运行时 chromeRuntimeChrome（application/json）；头部：Cache-Control
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
GET/screen/manifest

获取运行时清单

每个会话的唯一运行时清单路径。schemaVersion 为 3。已解析播放器清单；投影是容错的，无效页面和原语被省略并列入诊断。

广告位页面仅包含配对会话授予的 adslot-v1；其他所有会话，包括匿名公共屏幕查看者，均显示无广告位页面的自有内容。根键保持 camelCase；广告位页面键保持 id、type、adslot_id 和可选的 snake_case visibility。

兼容性规则 4 — 返回 200 且 pages 为 []、diagnostics 非空，表示降级投影（播放器保持最后已知良好状态）；返回 200 且 pages 为 []、没有 diagnostics，表示作者设定的空分配（docs/player-compatibility.md §1.4）。

已暂停的屏幕收到的 pages 为 []、没有 diagnostics，并带有 suspension 成员和自己的清单修订版本，无论是否分配了播放列表（§6.9）。归档屏幕返回问题 screen_archived，且不得刷新最后已知良好状态。

身份验证
runtimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
getRuntimeManifest

参数

名称发送必需？描述
stream_transports查询可选

以逗号分隔的支持的流传输方式（hls，udp-mpegts，rtsp）。省略表示流投射到备用图像。仅用于渲染协商，绝不用于授权。仅在本地启用时广告udp-mpegts。

请求模板和响应
shell · 请求模板
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifest'

响应

状态含义正文和头部
200已解析的播放器清单。运行时清单（application/json）
304清单未更改无正文
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
GET/stream/events

流运行时事件

身份验证
runtimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
streamRuntimeEvents

参数

名称发送必需？描述
after查询可选

先前响应的游标：ev1_ 用于项目事件（及事件流）。播放器日志（source=log）使用 lg1_ 或 ev1_ 游标分页，依据服务器存储位置；视为不透明并传回页面返回的游标。其他类型游标返回 invalid_request。

Last-Event-IDheader可选在 after 缺失时使用持久游标。
请求模板和响应
shell · 请求模板
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/stream/events'

响应

状态含义正文和头部
200

屏幕范围的持久 SSE。查询游标优先于 Last-Event-ID；每个事件携带适合重连的 id 游标。由 Valkey（stream-valkey/v1）流边车提供；流不携带 stream.cursor 帧，游标仅随已传递事件前进。

无效、未来或保留前游标在当前头部接收 stream.resync_required 并关闭。screen.toast 和 screen.screenshot_requested 是运行时观众事件；扫描永远不会传递过去的 details.expires_at。

截图图像字节永远不会出现在此流中。screen.archived 和 screen.unarchived 是运行时观众事件；它们不会清除凭据。screen.deleted 是当签名身份重置墓碑屏幕时传递的运行时观众事件。没有运行时事件授权清除本地身份。

仅成功签名的重置且由确认的本地播放器操作发起，允许本地身份轮换。project.suspended 和 project.resumed 是预付剩余次数为零或变正时的运行时受众提示。

运行时受众是一个允许列表（docs/player-compatibility.md §7.1）：screen.content_changed、screen.manifest_changed、screen.toast、screen.screenshot_requested、screen.archived、screen.unarchived、screen.deleted、screen.device_credential_revoked、project.suspended、project.resumed、player.reload（送达每个运行时会话）、每屏命令 player.reboot 和 player.display（docs/player-compatibility.md §6.5）、player.play_page（§6.3.1）和 player.identify（§6.3.2）（这些命令绝不会在 details.expires_at 之后送达），以及 screen.card_data_changed（resource {type: card_data, key}，details {revision} 或 {deleted: true}），后者仅发给当前内容读取该卡片数据或 feed 键的屏幕。

其他类型永远不会发布到流。播放器忽略未知事件类型（包括默认消息类型）和未知字段名，并从每个 id 推进游标。

流以自身重试开启，每个连接间隔 3000 到 15000 毫秒，避免同时断流的流同时重连；排空主机为每个流发送 1000 到 30000 毫秒的重试间隔。

带内问题帧（事件：problem）无 ID；其数据为 {code, detail, action?}，当注册表定义了 action 时存在，随后流关闭（payment_required 设置重试：60000）。舰队 player.reload 控制帧无 ID，且从不移动光标。无帧携带超过 64 KiB 的数据。

字符串（text/event-stream）；头部：X-Accel-Buffering
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/reports

创建运行时报告

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
inline
操作 ID
createRuntimeReport
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/reports'

响应

状态含义正文和头部
202

在持久保存后接受。遥测批次作为一个单元被接受或拒绝。仅当其原始观测持久保存且流水印已移动后，才返回 202；返回 stream_id、sequence、accepted（报告计数）和 duplicate。

一个批次更改最新健康或观察状态或页面失败槽，或追加项目事件，在一次屏幕写入中提交其水印和状态，并在同一事务中追加事件。

一个批次未更改任何内容，如稳定的播放和条件报告批次，仅移动其水印，在 Valkey 中保持 25 小时；Valkey 不可用或内存不足时，屏幕写入保持它。

被拒绝的批次（冲突重放、流容量已满、权限已注销）不存储任何内容，除非一个新流会夺走屏幕最后的流位置给并发的新流，该新流在存储其原始观察后被拒绝。

因服务器错误或连接丢失未确认的批次可能存储了部分原始观察；重放相同字节存储每个缺失观察一次，绝不重复存储，然后确认。重放已确认批次返回 202，带 duplicate true，且不更改任何内容。

Valkey 中持有的水印可能在故障切换中丢失或滞后，绝不超前，因此序列超过流水印被接受为流的下一个，无间隙拒绝，丢失水印的重放再次接受，duplicate 为 false；其播放仍存储一次，播放器日志记录按身份合并。

单个报告保留其现有响应。

运行时状态报告（任何其他报告代码，如 player.page_skipped）记录在播放器日志（GET /api/events?source=log）中，不在项目事件中，且当播放器日志队列接受时被确认；它不在事件流中，也不传送给 webhook。manifest.activated 在此响应前提交，并对当前活动修订幂等。playback.media_started、旧版 playback.video_started 和 playback.application_started 在此响应前持久追加一个经过身份验证的屏幕观察（GET /api/playback/plays）；报告的项目、页面和清单身份不要求当前内容成员资格，也不授权内容访问。

每日计数、可选元数据及项目拥有资源的 last_used_at 由可恢复批处理更新，可能滞后于原始观测。

普通播放开始响应省略可选额度余额头。playback.page_failed 替换屏幕的最新页面失败时段，并在同一事务中追加仅项目持久事件，且不更改屏幕或清单修订。manifest.upgrade 将屏幕的最新胜出清单升级时段存储在其修订栅栏后，并仅当派生状态更改时在同一事务中追加仅项目持久事件；接受过期、被取代或激活前报告，无更改，且无报告提升授权。application.event 在此响应前追加持久项目事件。

无正文；头部：RateLimit-Policy、RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/screenshot

放置运行时截图

上传当前会话屏幕的待处理静态 WebP。路径不指定 screen_id；配对的运行时会绑定它。请求头 ScreenRig-Capture-Id 必须是当前待处理的 capture_id。Content-Type 必须是 image/webp。主体是原始 WebP，非空，最大 2097152 字节。

服务器验证 RIFF/WEBP 魔术字，解码一帧静态图像，并存储上传的字节不变。动画 WebP 是 invalid_request。缺失、未知、过期或非当前的 capture_id 是 resource_conflict。禁止未配对会话。预付剩余额度不是门槛，这些字节不计入 used_bytes。

每个屏幕替换一个插槽。screen.screenshot_ready 详情包括 name、capture_id、bytes、width、height 和 sha256；不包含像素数据或对象键。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
string
操作 ID
putRuntimeScreenshot

参数

名称发送必需？描述
ScreenRig-Capture-Idheader必填
ScreenRig-Capture-Failureheader可选

报告不可用捕获时发送空体。播放器发送unsupported_surface或capture_failed。其他非空值记录为capture_failed，绝不拒绝（docs/player-compatibility.md §1.1）。仅当前待处理捕获可能失败。

未存储任何像素或部分图像；screen.screenshot_failed 包含此原因，状态变为不可用。

请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'ScreenRig-Capture-Id: VALUE' --header 'Content-Type: image/webp' --data-binary '@request.bin' 'https://play.screenrig.ai/screen/screenshot'

响应

状态含义正文和头部
204当前槽位存储的静态 WebP。无正文；头部：Cache-Control
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/adslots/resolve

解析广告位

解析最多 16 个服务器验证的页面出现。带可能填充的新候选项会原子性定价、预算检查并预留于整个广告活动的价格限制内。无可能填充的新候选项返回空，不创建决策或预留。

无合格或可负担的广告活动是成功的空结果，无内容且无扣款；绝非支付挑战。空结果可能包含服务器时钟无填充提示，最长 60 秒，且在已知资格边界之前结束。

提示适用于相同的屏幕、清单、页面、插槽和资格上下文；它们从不授权播放。租约续订重用相同预订且不推进轮换，且在广告活动需要重新接受价格时被拒绝。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeAdslotResolveRequest
操作 ID
resolveAdslots

请求主体字段

字段描述
manifest_revision（必填，字符串）
候选项（必填，数组）
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/adslots/resolve'

响应

状态含义正文和头部
200按请求顺序计算的每个候选项填充或空结果。RuntimeAdslotResolveResponse（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
400invalid_request - 批量大小、重复键或预测窗口无效。运行时问题（application/problem+json）
409resource_conflict - 候选项被重复使用但请求哈希不同。运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/adslots/events

报告广告位事件

经过身份验证的播放证据。事件在屏幕和事件 ID 上去重。有效完成一次消耗其持有的预订，按预订价格和费用，卖方记入总额，服务费扣除，一笔交易完成。确认的非播放终端事件释放一次持有。

发布后的完成不计费且永不扣除新额度。开始前的完成待对账。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeAdslotEventBatch
操作 ID
reportAdslotEvents

请求主体字段

字段描述
事件（必填，数组）
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/adslots/events'

响应

状态含义正文和头部
200每个事件结果。RuntimeAdslotEventResponse（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/observation

放置运行时观察

报告配对播放器用于最后一次 resolveLayout 的播放表面。路径不包含 screen_id；由配对的运行时会话绑定。主体为 JSON 格式的 ScreenObservation：包含 observed_at 及一到十二个表面；驱动视频墙的播放器每个输出报告一个，id 为输出名称。

数字为设备无关像素及该布局表面的设备像素比，不是画布作者大小，也非编码截图大小。仅进行范围检查，绝不证明硬件或授权。最后写入胜出，替换整个 surfaces 数组。

相同的表面元组（ID、宽、高、pixel_ratio、展示、旋转）不会触发 screen.surface_changed；同一元组的后续 observed_at 被忽略。禁止未配对和匿名公共会话。拒绝本地 Cookie；浏览器不得采用头部配置。预付剩余信用不是门槛。

在第一次接受的报告之前，GET /api/screens 中不包含观察数据。ScreenPatch 无法写入。归档屏幕返回 409 screen_archived。每个配对会话（runtime-observation）每分钟最多 12 次报告：429 表示请在 Retry-After 指定时间后重试。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
运行时观察写入
操作 ID
putRuntimeObservation

请求主体字段

字段描述
observed_at（必填，字符串）格式：“date-time”
surfaces（必填，数组）一到十二个表面；驱动视频墙的播放器每个输出报告一个，id 为输出名称。
请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/observation'

响应

状态含义正文和头部
204观察数据存储为当前的 surfaces 数组。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/health

放置运行时健康状态

报告配对会话屏幕的设备健康状况。在会话开始时和每十五分钟发送一次，当显示连接或电源发生变化时立即发送一次。

每个成员都是可选的，主体内容容错读取（详见 docs/player-compatibility.md §1.1）：忽略未知成员，丢弃超出范围的值，未知的 display.power 或 network.kind 视为未知；只有类型错误的成员返回 400（超出 float64 范围的数字视为超出范围，该成员被丢弃）。

存储值为净化后的 ScreenHealth 加服务器 reported_at，替代之前报告。每屏最多每分钟一份报告（runtime-health）：429 表示丢弃此报告，按计划发送下一份，重试不得早于 Retry-After（至少 1 秒）。

400 或服务器错误不消耗一分钟；同一屏幕的所有会话共享此时间。需要持有 health.write 权限的配对会话（在 health.write 存在之前创建的配对会话由 runtime.report 允许）；禁止未配对和匿名会话，归档屏幕返回 409 screen_archived。

来自早于屏幕当前内容访问代的会话报告被拒绝，返回 401。归档和屏幕恢复会清除 Screen.health。没有此路由的后端返回 404：继续播放并停止该会话的健康报告。过渡附加仅限项目的 screen.health_changed（从不在 GET /screen/events 上）。

健康绝非授权。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
运行时健康写入
操作 ID
putRuntimeHealth

请求主体字段

字段描述
uptime_s（可选，整数）设备（操作系统）启动后的秒数。最小值：0
app_uptime_s（可选，整数）播放器进程启动后的秒数。最小值：0
memory（可选，对象）
cpu（可选，对象）
temperature_c（可选，数字）SoC 或面板温度，单位摄氏度。最小值：-50 最大值：150
display（可选，对象）
网络（可选，对象）
battery（可选，对象）设备的电池。仅在设备带有电池时发送（Android BatteryManager 与 EXTRA_PRESENT）。供电来源的变化（接通或断开电源）会立即报告，与显示变化一样。
crashes_24h（可选，整数）播放器在过去 24 小时内崩溃次数。最小值：0 最大值：1000000
renderer_restarts_24h（可选，整数）渲染器或网页视图在过去24小时内的重启次数。最小值：0 最大值：1000000
请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/health'

响应

状态含义正文和头部
204健康报告已存储。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/storage

放置运行时存储

报告本地播放器存储、播放器的存储计划和传输字节计数。路径不包含 screen_id；由配对的运行时会话绑定。禁止未配对和匿名会话。拒绝本地 cookie；浏览器不得采用头部配置文件。未知成员将被忽略（docs/player-compatibility.md §1.1）。

存储值为净化后的项目 ScreenStorage 加服务器 received_at，不是原始主体。manifest_revision 必须为屏幕期望或活动版本，否则响应 409 resource_conflict，且不存储。排除的页面 ID 必须存在于该版本中。

相同的适配类不会触发 screen.storage_shortfall 或 screen.storage_shortfall_cleared。这些事件仅限项目，不通过 GET /screen/events. 传递。存储永远不是授权或准入。ScreenPatch 无法写入。超过 24 小时的报告由 received_at 视为过期。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
运行时存储写入
操作 ID
putRuntimeStorage

请求主体字段

字段描述
observed_at（必填，字符串）格式：“date-time”
volume（必填，ScreenStorageVolume）
cache（必填，ScreenStorageCache）
durability（必填，字符串）允许：“durable”、“purgeable”
计划（必填，ScreenStoragePlan）
transfer_24h（必填，ScreenStorageTransfer）
请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/storage'

响应

状态含义正文和头部
204存储报告已保存。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409resource_conflict - manifest_revision 不是屏幕的期望或活动版本。报告未被存储。运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/status

放置运行时状态

报告配对播放器在屏幕上显示的状态芯片：在排名中胜出的 screenrig.overlay/v1 条件；不显示芯片时为 null。路径不包含 screen_id；由配对的运行时会话绑定。

请求体为 JSON 格式的 RuntimeStatusWrite {observed_at, chip}；未知成员被忽略（docs/player-compatibility.md §1.1）。chip 必须是后端目录（packages/overlay/overlay.json，播放器内置的文件）中某个条件的 id；升级通知和启动消息不是芯片。

缺少 chip、值为其他类型或 id 不在目录中，将返回 400 invalid_request，errors[0].field 为 chip，且不存储任何内容。存储值为项目的 ScreenStatus：level 和 icon 取自目录中 chip 对应的条目，绝非播放器提供，received_at 为服务器接收时间。最后写入胜出，替换整个状态。

不更改 chip、level 和 icon 中任何一项的报告不执行任何操作：保留已存储的 observed_at 和 received_at，且不追加任何内容。发生更改时，附加仅限项目的 screen.status_changed，其 details 为 {chip, level, icon}，从不在 GET /screen/events 上传递。禁止未配对和匿名的公开会话。

拒绝本地 Cookie；浏览器不得采用头部配置。预付剩余信用不是门槛。在首次接受的报告之前，GET /api/screens 中不包含状态，并在身份重置、取消配对和归档时清除。ScreenPatch 无法写入。归档屏幕返回 409 screen_archived。

每个配对会话（runtime-status）每分钟最多 12 次报告：429 表示请在 Retry-After 指定时间后重试。没有此路由的后端返回 404：继续播放并停止该会话的状态报告。状态绝不是授权或准入。播放器规则见 docs/player-compatibility.md §9.5。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
运行时状态写入
操作 ID
putRuntimeStatus

请求主体字段

字段描述
observed_at（必填，字符串）芯片最近一次变化或会话开始时的播放器时钟。格式：“date-time”
chip（必填，内联）

播放器显示的 screenrig.overlay/v1 条件的 id（packages/overlay/overlay.json 中的 conditions[].id）；不显示芯片时为 null，例如在被抑制的表面上（fatal、starting、pairing）。必填。后端目录中没有的 id 会被拒绝。

请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/status'

响应

状态含义正文和头部
204状态已存储或未更改。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/screen-label

放置运行时屏幕标签

重命名绑定到配对运行时会话的屏幕。此操作等同于 PATCH /api/screens/{id} 的 name：服务器会去除 screen_label 首尾的空白，要求 1 至 120 个字符且无控制字符，否则返回 invalid_request。

重命名记录相同的屏幕事件，并在分配的屏幕上更改清单 screen_label 并向播放器发出 screen.manifest_changed。路径和主体不命名 screen_id；配对的运行时会话绑定它。无 If-Match 或 Idempotency-Key；最后写入者获胜。认证是运行时 cookie 或 ScreenRig-Session，如 GET /screen/chrome.。

匿名和未配对会话未经授权。归档屏幕为screen_archived。预付剩余额度不是门槛。收到404的播放器将该路由视为不支持并本地保留名称（docs/player-compatibility.md §2.5）。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
运行时屏幕标签写入
操作 ID
putRuntimeScreenLabel

请求主体字段

字段描述
screen_label（必填，字符串）minLength：1
请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/screen-label'

响应

状态含义正文和头部
200屏幕已重命名。screen_label 是存储的名称。运行时屏幕标签（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/commands/{command_id}/result

提交运行时命令结果

配对的播放器报告其收到的命令如何结束（docs/player-compatibility.md §6.5.1）：done 或 failed，附带静态 cause 令牌和可选的简短 detail。命令在 Screen.commands 中变为 done 或 failed，带有 done_at、cause 和 detail，并追加仅限项目的 screen.command_result。

只有会话所属屏幕的 sent 命令才接受结果：屏幕未列出的 id，或未发送的命令，返回 404 not_found，播放器丢弃该报告。与已记录结果完全相同的重复提交返回 202 且不产生任何变化；对已完成命令提交不同的结果返回 409 resource_conflict。failed 结果需要 cause。

路径和请求体都不指明屏幕；由配对的运行时会话绑定。认证使用运行时 Cookie 或 ScreenRig-Session。匿名和未配对的会话为 unauthorized；归档屏幕为 screen_archived。预付的剩余额度不是门槛。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeCommandResultWrite
操作 ID
postRuntimeCommandResult

参数

名称发送必需？描述
command_id路径必填

请求主体字段

字段描述
state（必填，字符串）允许："done", "failed"
cause（可选，字符串）

静态令牌：failed 时必填（clear_failed, restart_failed, update_check_failed, download_failed, install_failed, no_update_channel），done 时可选（cleared, restarted, up_to_date, updated）。pattern: "^[a-z0-9_]{1,40}$"

detail（可选，字符串）不含控制字符的简短句子；绝不是带凭据的 URL、令牌或私有路径。maxLength: 200
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/commands/COMMAND_ID/result'

响应

状态含义正文和头部
202已存储，或与已存储结果完全相同的重复提交。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
404

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/live/{live_id}/join

加入实时会话

收到 player.live_publish 的 Player 会加入该会话（docs/player-compatibility.md §6.10.2）：它会获得短期有效的 TURN ice_servers、租约、可推送的视频上限以及心跳周期。live_id 必须是屏幕当前的会话，否则返回 410 live_session_ended（停止推流并继续播放）。

认证使用已配对的运行时 Cookie 或 ScreenRig-Session。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeLiveJoinRequest
操作 ID
joinRuntimeLive

参数

名称发送必需？描述
live_id路径必填
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/join'

响应

状态含义正文和头部
200Player 推流所用的会话。RuntimeLiveJoin（application/json）；头信息：Cache-Control, RateLimit-Policy, RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
410

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/live/{live_id}/offer

实时会话提议

The Player sends its gathered sendonly offer: exactly one video m-section, ICE gathering complete or two seconds old, no separate candidates ever. The backend opens a fresh media relay session for it, replacing any earlier publisher of the session, and returns the relay's answer, which the Player applies with setRemoteDescription.

没有视频 m 段或有两个时返回 invalid_request。中继故障返回 dependency_unavailable。live_id 不是屏幕当前会话时返回 410 live_session_ended。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeLiveOffer
操作 ID
offerRuntimeLive

参数

名称发送必需？描述
live_id路径必填

请求主体字段

字段描述
sdp（必填，字符串）恰好一个 sendonly 视频 m 段；ICE 收集已完成或已满两秒。
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/offer'

响应

状态含义正文和头部
200中继的应答。RuntimeLiveOffer（application/json）；头信息：Cache-Control, RateLimit-Policy, RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
410

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/live/{live_id}/heartbeat

实时会话心跳

The Player reports its connection state and what its encoder sends every 20 seconds. The answer carries the lease; a lapsed lease or max_until ends the session here with 410 live_session_ended, and the Player stops publishing. The report is the Player's own word and feeds publisher.connected on the project API.

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeLiveHeartbeat
操作 ID
heartbeatRuntimeLive

参数

名称发送必需？描述
live_id路径必填

请求主体字段

字段描述
connection（必填，字符串）允许："new", "connecting", "connected", "disconnected", "failed", "closed"
video（可选，object）
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/heartbeat'

响应

状态含义正文和头部
200会话正在进行；lease_until 和 max_until 是其上限。RuntimeLiveHeartbeatAnswer（application/json）；头信息：Cache-Control, RateLimit-Policy, RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
410

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/live/{live_id}/stopped

实时会话已停止

The Player reports it stopped publishing. The reason is an open enum (stopped, lease_ended, superseded, consent_denied, consent_timeout, projection_stopped, capture_failed, encoder_unavailable, connection_failed, relay_refused); a reason this server does not know reads player_stopped. 204 always, also for a live_id that is not the screen's current session.

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
RuntimeLiveStopped
操作 ID
stoppedRuntimeLive

参数

名称发送必需？描述
live_id路径必填

请求主体字段

字段描述
原因（必填，字符串）

stopped, lease_ended, superseded, consent_denied, consent_timeout, projection_stopped, capture_failed, encoder_unavailable, connection_failed or relay_refused. An open enum; an unknown reason reads player_stopped.

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/stopped'

响应

状态含义正文和头部
204已记录。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
410

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
GET/screen/playlists

获取运行时屏幕播放列表

列出配对播放器设备设置菜单为屏幕提供的播放列表：屏幕项目中具有已批准版本的实时播放列表，按名称字母顺序（不区分大小写）排序，然后按 ID 排序。最多返回 500 个；如果项目有更多播放列表，则为 true。

配对的运行时会话绑定项目；路径名为 none。认证是运行时 cookie 或 ScreenRig-Session，如 GET /screen/chrome.。匿名和未配对会话未经授权。归档屏幕为 screen_archived。Cache-Control 是私有的，不存储。

收到 404 的播放器将路由视为不支持，并像加载列表失败一样报告（docs/player-compatibility.md §2.6）。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
getRuntimeScreenPlaylists
请求模板和响应
shell · 请求模板
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/playlists'

响应

状态含义正文和头部
200项目可分配的播放列表。运行时屏幕播放列表集合（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
PUT/screen/playlist

放置运行时屏幕播放列表

将播放列表分配给绑定配对运行时会话的屏幕。与设备人员执行的 PATCH /api/screens/{id} playlist_id 相同：不打开审核。

播放列表必须属于屏幕的项目并拥有已批准版本（否则为 playlist_not_approved）；项目中不存在的播放列表为 invalid_request。分配记录相同的屏幕事件并向播放器发出 screen.manifest_changed。

设置屏幕分配的播放列表；活动接管或匹配的播放列表调度条目仍决定播放内容。路径和主体不命名 screen_id；配对的运行时会话绑定它。无 If-Match 或 Idempotency-Key；最后写入生效。认证为运行时 cookie 或 ScreenRig-Session，如 GET /screen/chrome.。

匿名和未配对会话未经授权。归档屏幕为screen_archived。收到404的播放器将该路由视为不支持，并像其他播放列表更改失败一样报告（docs/player-compatibility.md §2.6）。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
运行时屏幕播放列表写入
操作 ID
putRuntimeScreenPlaylist

请求主体字段

字段描述
playlist_id（必填，字符串）minLength：1
请求模板和响应
shell · 请求模板
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/playlist'

响应

状态含义正文和头部
200播放列表已分配。playlist_id 是屏幕分配的播放列表。运行时屏幕播放列表（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
400

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/unpair

取消配对运行时

仅 Cookie 解除配对。归档一个没有播放器公钥注册的 Cookie 配对屏幕，使用 archive_reason device_unpair。设备凭证保持绑定：仍持有它的浏览器会生成一个归档会话（暗玻璃），取消归档时恢复，无需重新配对（文档/player-compatibility.md §5.1）。

已归档或已消失的屏幕视为成功。身份注册的屏幕返回 screen_archive_required；这些播放器仅通过 POST /screen/native/identity/reset. 重置，路径和主体不包含 screen_id；配对的运行时会话绑定它。无 If-Match 或 Idempotency-Key。浏览器 204 会使运行时、设备和配对主机 Cookie 失效。

原生身份绑定调用永不返回 204。禁止匿名或未配对的会话。预付剩余额度不是门槛。

身份验证
pairedRuntimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
unpairRuntime
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/unpair'

响应

状态含义正文和头部
204Cookie 配对屏幕归档，凭证保留。浏览器配对 Cookie 已过期。无正文；头部：Cache-Control、RateLimit-Policy、RateLimit
401

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
403

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
409

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
429

面向播放器的运行时或内容路由上的稳定 rate_limited 问题，采用运行时文档格式（RuntimeProblem）。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

运行时问题（application/problem+json）；头部：Retry-After，RateLimit-Policy，RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/manifests/{manifest_revision}/releases/{release_id}/launch

启动应用发布

为屏幕当前清单的某个应用发布版本生成一次性票据。launch_url 是发布主机的索引页，先带 ticket，再带应用的 params（该原语的 params，填入此屏幕的信息，经百分号编码，合计最多 4096 个字符），因此应用从 location.search 读取它们。

只有 Web 播放器及运行它的播放器会调用此路由；Qt、Android、Apple 和 Windows 播放器从本地包加载应用，不接收 params。发布主机会将它们传递给页面，并添加自己的策略标记。

屏幕缺少某个参数所读取的值，或其值填入后超过限制，则其清单中没有此类应用（诊断 screen_fact_missing 或 screen_fact_invalid），其发布版本的启动也会被拒绝。

Params 不绑定到票据：应用将其视为不受信任的提示，并从 context.screen_id 读取屏幕身份。

身份验证
runtimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
launchApplicationRelease

参数

名称发送必需？描述
manifest_revision路径必填
release_id路径必填
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifests/MANIFEST_REVISION/releases/RELEASE_ID/launch'

响应

状态含义正文和头部
201一次性使用的 30 秒精确发布主机启动票证ReleaseLaunch（application/json）；头部：Referrer-Policy、RateLimit-Policy、RateLimit
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
POST/screen/manifests/{manifest_revision}/selectors/resolve

解析一个播放列表循环中的所有动态媒体选择器

使用经过身份验证的屏幕分配的播放列表及其清单修订版。返回按文件名顺序的固定快照；播放器在循环间保留光标和随机状态。上传和标签更改永不重写此清单。空匹配有效。

所选媒体由屏幕的运行时授权独立于不可变清单定义。

身份验证
runtimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
resolveRuntimeSelectors

参数

名称发送必需？描述
manifest_revision路径必填
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/screen/manifests/MANIFEST_REVISION/selectors/resolve'

响应

状态含义正文和头部
200已解析的循环快照，包括项目元数据和 media_end 安全截止时间。运行时选择器快照（application/json）
401运行时会话无效或过期运行时问题（application/problem+json）
403运行时能力被拒绝运行时问题（application/problem+json）
503清单投影待定或选择器快照降级；保持当前循环并重试运行时问题（application/problem+json）
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）
GET/screen/card-data/{key}

获取运行时卡片数据

返回卡片数据或订阅文档：即屏幕当前清单中卡片原语的卡片数据或订阅键，或页面 visibility.data 条件的键所对应的文档。仅当会话屏幕的所需、活动或过渡宽限授权列出该键时，键才可读取；仅知晓键永远不够。

Feed 键以 feed: 开头，读取系统 Feed 命名空间（screenrig.weather/v1 及其他 Feed 架构）；以 feed.conditions.v1: 开头的天气条件键也一样（页面的 {screen.weather} 条件，由每个屏幕的清单填入）；其他所有键读取屏幕项目的卡片数据。主体即为文档本身。

ETag 是其字节的 sha256，If-None-Match 返回 304；离线播放保留最后一个有效文档，并在 screen.card_data_changed 时重新获取。404 表示尚无存储文档；保持卡片隐藏。

身份验证
runtimeCookie 或 nativeSessionAuthorization
请求主体
无
操作 ID
getRuntimeCardData

参数

名称发送必需？描述
key路径必填
If-None-Matchheader可选
请求模板和响应
shell · 请求模板
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/card-data/KEY'

响应

状态含义正文和头部
200文档对象（application/json）；头部：ETag
304未修改无正文
默认

面向播放器的运行时、内容或探测路由上的稳定 RFC 9457 问题响应，采用运行时文档格式（RuntimeProblem）。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

运行时问题（application/problem+json）