screenRIG
登录开始使用

API 参考

配对与会话 API

播放器配对和会话

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

OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览

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

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

播放器配对和会话

POST/screen/pairing-sessions

开始配对会话

创建一个车队全局过期配对会话，并设置临时 HttpOnly Secure SameSite=Strict 配对 Cookie。不受信任的来源或跨站浏览器请求在创建速率限制或配对状态前被拒绝，返回 forbidden。

身份验证
无
请求主体
无
操作 ID
startPairingSession
请求模板和响应
shell · 请求模板
curl --request POST 'https://play.screenrig.ai/screen/pairing-sessions'

响应

状态含义正文和头部
201确切的六字符配对码及其过期时间。PairingSession（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
403

面向播放器的运行时、内容或探测路由上的稳定 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/stream/pairing-events

流配对事件

身份验证
pairingCookie
请求主体
无
操作 ID
streamPairingEvents
请求模板和响应
shell · 请求模板
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/stream/pairing-events'

响应

状态含义正文和头部
200经过身份验证的临时配对 SSE。终端 pairing.claimed 数据为 PairingClaimedEvent，仅包含非秘密完成随机数。字符串（text/event-stream）；头部：Cache-Control、X-Accel-Buffering
401

面向播放器的运行时、内容或探测路由上的稳定 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/pairing-sessions/complete

完成配对会话

身份验证
pairingCookie
请求主体
配对完成
操作 ID
completePairingSession

请求主体字段

字段描述
completion_nonce（必填，字符串）模式："^[A-Za-z0-9_-]{43}$"
请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/pairing-sessions/complete'

响应

状态含义正文和头部
200已配对设备 cookie 已发出；播放器接下来创建普通的已配对运行时会话。PairingCompletion（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）
404

面向播放器的运行时、内容或探测路由上的稳定 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）
POST/screen/sessions

创建匿名运行时会话

身份验证
无
请求主体
运行时会话请求
操作 ID
createAnonymousRuntimeSession

请求主体字段

字段描述
public_id（必填，字符串）
播放（可选，PlaybackHandshake）

播放器在 mint 时声明的可选播放握手。它是选择行为的提示，绝非授权：未知成员和错误类型条目被忽略，非对象值不协商任何内容。mint 响应回显支持的交集为 PlaybackGrant。adslot-v1 仅授予配对会话。

播放器（可选，PlayerIdentity）

播放器自我识别，仅在三个 mint 路由上发送（docs/player-compatibility.md §3.1）。它是提示而非授权，且不包含在本地证明中。读取时容错：忽略未知成员，丢弃无效的可选成员，非对象或无有效类型的播放器不声明任何内容。

永远不会返回 400。配对的 mint 会将其存储在屏幕上以供操作员舰队直方图使用。

请求模板和响应
shell · 请求模板
curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/sessions'

响应

状态含义正文和头部
201只读运行时会话 cookie运行时会话（application/json）；头部：RateLimit-Policy，RateLimit
404

面向播放器的运行时、内容或探测路由上的稳定 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/device-sessions

创建设备运行时会话

身份验证
pairedDeviceCookie
请求主体
DeviceSessionRequest
操作 ID
createDeviceRuntimeSession

请求主体字段

字段描述
public_id（可选，字符串）minLength：1
播放（可选，PlaybackHandshake）

播放器在 mint 时声明的可选播放握手。它是选择行为的提示，绝非授权：未知成员和错误类型条目被忽略，非对象值不协商任何内容。mint 响应回显支持的交集为 PlaybackGrant。adslot-v1 仅授予配对会话。

播放器（可选，PlayerIdentity）

播放器自我识别，仅在三个 mint 路由上发送（docs/player-compatibility.md §3.1）。它是提示而非授权，且不包含在本地证明中。读取时容错：忽略未知成员，丢弃无效的可选成员，非对象或无有效类型的播放器不声明任何内容。

永远不会返回 400。配对的 mint 会将其存储在屏幕上以供操作员舰队直方图使用。

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

响应

状态含义正文和头部
201已配对的运行时会话运行时会话（application/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/native/pairing-sessions

开始本地配对会话

从播放器 Ed25519 公钥创建仅限本地的配对会话。未认领的本地配对持续七十二小时。成功认领后保留屏幕并独立于定位器过期存储持久加密交付。直到该配对凭据和随机数的签名完成，公钥不会绑定到项目。

拒绝 Cookie、查询凭证、跨站点来源和授权。精确 Idempotency-Key 重放优先于新滥用许可。响应从不设置 Cookie。已绑定或明确注销的公钥返回 enrollment_bound。

身份验证
无
请求主体
NativePairingStart
操作 ID
startNativePairingSession

参数

名称发送必需？描述
Idempotency-Keyheader必填

请求主体字段

字段描述
kid（必填，字符串）模式："^[A-Za-z0-9_-]{43}$"
public_key（必填，PlayerPublicKey）
签名（必填，字符串）minLength：80 maxLength：4096
host（可选，RuntimeHostHint）

配对开始、配对完成和身份会话生成时的可选本机主机提示。它命名设备，绝不作为授权。

容错读取（docs/player-compatibility.md §1.1.1）：忽略未知成员，丢弃格式错误字段或能力条目，最多保留 32 个能力，非对象值或模式外平台丢弃整个提示。以上均不拒绝请求。

播放器仍只发送注册的平台值和以下成员，因为预合同后端拒绝其他内容。

fleet_link（可选，字符串）

来自 Player URL 片段（#fleet=）的可选设备群链接密钥。有效、已启用且未过期的链接会立即为其项目认领此配对会话，或找回该设备此前的屏幕；响应中的 fleet_link 会说明是哪一种。

与 host 一样，它会被宽松解析：格式错误或未知的值绝不会导致启动请求被拒绝。pattern: "^srfl_[A-Za-z0-9_-]{43}$"

请求模板和响应
shell · 请求模板
curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/pairing-sessions'

响应

状态含义正文和头部
201原生配对码加临时 ScreenRig-Pairing 凭证；无 Set-Cookie。NativePairingSession（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）
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
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/stream/native/pairing-events

流原生配对事件

仅限原生配对的 SSE，由恰好一个 ScreenRig-Pairing 授权头认证。拒绝 Cookie 和查询凭证。终端事件仅包含非秘密完成随机数。

身份验证
nativePairingAuthorization
请求主体
无
操作 ID
streamNativePairingEvents
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: ScreenRig-Pairing PAIRING' 'https://play.screenrig.ai/stream/native/pairing-events'

响应

状态含义正文和头部
200经过身份验证的本地配对 SSE，终端数据为 PairingClaimedEvent。字符串（text/event-stream）；头部：Cache-Control、X-Accel-Buffering
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）
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）
POST/screen/native/pairing-sessions/complete

完成本地配对会话

通过完成随机数和带有op=pairing.complete的EdDSA紧凑JWS完成本地配对，其request_hash绑定精确配对凭证和完成随机数。不接受或设置cookie。不发放ScreenRig-Device凭证。播放器随后从持有证明中铸造ScreenRig-Session。

身份验证
nativePairingAuthorization
请求主体
NativePairingComplete
操作 ID
completeNativePairingSession

请求主体字段

字段描述
kid（可选，字符串）模式："^[A-Za-z0-9_-]{43}$"
completion_nonce（必填，字符串）模式："^[A-Za-z0-9_-]{43}$"
public_key（必填，PlayerPublicKey）
签名（必填，字符串）紧凑型 EdDSA JWS，操作为 pairing.complete，并用 request_hash 绑定精确的配对凭证和完成随机数。minLength：80 maxLength：4096
host（可选，RuntimeHostHint）

配对开始、配对完成和身份会话生成时的可选本机主机提示。它命名设备，绝不作为授权。

容错读取（docs/player-compatibility.md §1.1.1）：忽略未知成员，丢弃格式错误字段或能力条目，最多保留 32 个能力，非对象值或模式外平台丢弃整个提示。以上均不拒绝请求。

播放器仍只发送注册的平台值和以下成员，因为预合同后端拒绝其他内容。

请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: ScreenRig-Pairing PAIRING' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/pairing-sessions/complete'

响应

状态含义正文和头部
200原生配对完成；无 Set-Cookie 且无设备凭证。NativePairingCompletion（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）
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
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）
POST/screen/native/identity/challenges

创建本地身份验证挑战

发放绑定到单个播放器公钥指纹的短期随机数。拒绝 Cookie、查询凭证和授权。

身份验证
无
请求主体
NativeIdentityChallengeRequest
操作 ID
createNativeIdentityChallenge

请求主体字段

字段描述
kid（必填，字符串）RFC 7638 SHA-256 JWK 指纹。模式："^[A-Za-z0-9_-]{43}$"
public_key（可选，PlayerPublicKey）
op（必填，字符串）允许值：“pairing.start”、“pairing.complete”、“session.mint”、“identity.reset”
request_hash（必填，字符串）模式："^[0-9a-f]{64}$"
请求模板和响应
shell · 请求模板
curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/challenges'

响应

状态含义正文和头部
201EdDSA 紧凑 JWS 证明的挑战随机数；无 Set-Cookie。NativeIdentityChallenge（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）
404

面向播放器的运行时、内容或探测路由上的稳定 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）
POST/screen/native/identity/sessions

创建本地身份验证运行时会话

验证 EdDSA 紧凑 JWS（op=session.mint）与已注册公钥，并返回签名的七天 ScreenRig-Session。配对播放器通过此相同签名铸币在一天后带抖动续订；续订替换凭证而不关闭现有运行时流。续订元数据对读取器是可选的，且不要求播放器更新。

不接受也不设置 Cookie。精确 Idempotency-Key 重放优先于新滥用许可。归档屏幕仍铸造会话，播放器可显示归档玻璃。会话铸造需签名完成建立的精确持久项目和屏幕绑定；待处理认领无会话权限。

精确重放重新检查绑定并拒绝已注销身份。

身份验证
无
请求主体
NativeIdentitySessionRequest
操作 ID
createNativeIdentityRuntimeSession

参数

名称发送必需？描述
Idempotency-Keyheader必填

请求主体字段

字段描述
kid（必填，字符串）模式："^[A-Za-z0-9_-]{43}$"
public_key（必填，PlayerPublicKey）
签名（必填，字符串）紧凑型 EdDSA JWS，操作为 session.mint。minLength：80 maxLength：4096
host（可选，RuntimeHostHint）

配对开始、配对完成和身份会话生成时的可选本机主机提示。它命名设备，绝不作为授权。

容错读取（docs/player-compatibility.md §1.1.1）：忽略未知成员，丢弃格式错误字段或能力条目，最多保留 32 个能力，非对象值或模式外平台丢弃整个提示。以上均不拒绝请求。

播放器仍只发送注册的平台值和以下成员，因为预合同后端拒绝其他内容。

播放（可选，PlaybackHandshake）

播放器在 mint 时声明的可选播放握手。它是选择行为的提示，绝非授权：未知成员和错误类型条目被忽略，非对象值不协商任何内容。mint 响应回显支持的交集为 PlaybackGrant。adslot-v1 仅授予配对会话。

播放器（可选，PlayerIdentity）

播放器自我识别，仅在三个 mint 路由上发送（docs/player-compatibility.md §3.1）。它是提示而非授权，且不包含在本地证明中。读取时容错：忽略未知成员，丢弃无效的可选成员，非对象或无有效类型的播放器不声明任何内容。

永远不会返回 400。配对的 mint 会将其存储在屏幕上以供操作员舰队直方图使用。

请求模板和响应
shell · 请求模板
curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/sessions'

响应

状态含义正文和头部
201已配对的本地运行时会话；无 Set-Cookie。NativeRuntimeSession（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）
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
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）
POST/screen/link-sessions

创建屏幕链接运行时会话

根据 Player 地址中的屏幕链接密钥（https://play.<domain>/player/#screen=… 中 #screen= 之后的 srsl_ 值），为不保留存储的浏览器签发有效期七天的 ScreenRig-Session。Player 每次加载时发送该密钥，续期时也再次发送；它不保存密钥或配对。

会话的设备密钥声明携带链接的 id，因此替换或删除链接会在 API 和边缘立即结束该会话。既不接受也不设置 Cookie。完全相同的 Idempotency-Key 重放先于任何新的防滥用准入。已归档的屏幕仍会签发会话，以便 Player 显示已归档状态。

被替换、已删除或未知的链接会返回 screen_link_invalid（401，操作 clear_lkg）。存在 host 时替换已保存的主机提示；player 替换已保存的 player。

身份验证
无
请求主体
ScreenLinkSessionRequest
操作 ID
createScreenLinkRuntimeSession

参数

名称发送必需？描述
Idempotency-Keyheader必填

请求主体字段

字段描述
screen_link（必填，字符串）模式："^srsl_[A-Za-z0-9_-]{43}$"
host（可选，RuntimeHostHint）

配对开始、配对完成和身份会话生成时的可选本机主机提示。它命名设备，绝不作为授权。

容错读取（docs/player-compatibility.md §1.1.1）：忽略未知成员，丢弃格式错误字段或能力条目，最多保留 32 个能力，非对象值或模式外平台丢弃整个提示。以上均不拒绝请求。

播放器仍只发送注册的平台值和以下成员，因为预合同后端拒绝其他内容。

播放（可选，PlaybackHandshake）

播放器在 mint 时声明的可选播放握手。它是选择行为的提示，绝非授权：未知成员和错误类型条目被忽略，非对象值不协商任何内容。mint 响应回显支持的交集为 PlaybackGrant。adslot-v1 仅授予配对会话。

播放器（可选，PlayerIdentity）

播放器自我识别，仅在三个 mint 路由上发送（docs/player-compatibility.md §3.1）。它是提示而非授权，且不包含在本地证明中。读取时容错：忽略未知成员，丢弃无效的可选成员，非对象或无有效类型的播放器不声明任何内容。

永远不会返回 400。配对的 mint 会将其存储在屏幕上以供操作员舰队直方图使用。

请求模板和响应
shell · 请求模板
curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/link-sessions'

响应

状态含义正文和头部
201已配对的本地运行时会话；无 Set-Cookie。NativeRuntimeSession（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
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）
POST/screen/native/identity/reset

重置本地身份

播放器上的重置，仅由设备上的明确确认操作触发。配对失败、会话生成或网络访问从不自动触发此操作或清除播放器本地密钥。端点验证 EdDSA 紧凑 JWS（op=identity.reset）。

绑定此密钥的屏幕因设备重置（archive_reason device_reset）被归档（已归档：无变化），且密钥仍绑定于该屏幕：仍持有密钥的设备会生成归档会话（暗屏），取消归档时恢复且无需重新配对，且该密钥无法启动新配对（enrollment_bound）。

待处理的本地声明要约已撤回。未绑定屏幕的密钥，或已被屏幕恢复退役的密钥，变为终态：无法再次配对或生成会话，重置退役密钥不会影响其继任者拥有的屏幕。

如果已注册项目被删除，签名重置使孤立密钥终端化，无需归档其他屏幕，设备可重新配对。丢失响应后，播放器保留本地密钥，可用新挑战和新签名证明重试。

网络错误本身不确认重置或授权清除该密钥（docs/player-compatibility.md §5.1）。无项目持有者。Cookie 不被接受或设置。

身份验证
无
请求主体
NativeIdentityProof
操作 ID
resetNativeIdentity

请求主体字段

字段描述
kid（必填，字符串）模式："^[A-Za-z0-9_-]{43}$"
public_key（必填，PlayerPublicKey）
签名（必填，字符串）紧凑型 EdDSA JWS。minLength：80 maxLength：4096
请求模板和响应
shell · 请求模板
curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/reset'

响应

状态含义正文和头部
204

记录重置：绑定实时项目的屏幕归档且保留密钥；已删除项目、未绑定或已退役密钥使终端失效；未知密钥作为幂等无操作响应且不归档。任何这些的认证重试也成功。无 Set-Cookie。

无正文；头部：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）
404

面向播放器的运行时、内容或探测路由上的稳定 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）