接入与鉴权

申请与审批复制章节链接

使用直播间 Key 调用 POST /v1/connect/requests，提交客户端信息与所需权限。instanceId 在安装时生成并保存；完整字段见申请连接。

响应提供 requestId、pollToken、userCode、expiresIn 和 interval。在客户端显示核对码，由直播间所有者或管理员在工作台核对并审批。申请有效期为 10 分钟。

Key 只允许申请接入，不能直接访问直播间。Key 默认长期有效，也可设置期限或随时撤销。获批后客户端应丢弃 Key，妥善保存令牌。

领取与刷新令牌复制章节链接

按返回的 interval 轮询 POST /v1/connect/token：

{"grantType": "request", "requestId": "<REQUEST_ID>", "pollToken": "<POLL_TOKEN>"}

未获批时返回 400，error.details.error 为 authorization_pending、slow_down、access_denied、expired_token 或 invalid_grant。只对待审批继续轮询，对限流放慢，拒绝或过期后重新处理连接。

Access Token 有效期为 1 小时；Refresh Token 有效期为 30 天，每次刷新轮换。刷新仍使用同一接口：

{"grantType": "refresh_token", "refreshToken": "<REFRESH_TOKEN>"}

刷新必须串行，旧令牌重复使用会撤销整个接入。无法确认刷新结果时重新申请，避免反复提交旧值。同一安装实例再次获批会替换它在本直播间的旧接入。

访问直播间复制章节链接

curl 'https://api.ailive.studio/v1/room' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

当前协议使用 Bearer 令牌，无需 DPoP 签名。凭据仅授权本直播间及批准的权限，不能替代工作台或管理端登录态。

不使用实时通道时，每 15 秒调用一次 POST /v1/room/heartbeat。使用实时通道时先领取短时、单次票据，再按客户端协议建立 WebSocket；不要把 Access Token 放进公开链接。

数据重发与退出复制章节链接

平台数据按来源上报，重发同一批次时保持 batchId，采集器每次启动使用新 epoch，其中 seq 连续递增。读取响应中的确认位置和缺失区间后补发。

调用 POST /v1/connect/revoke 撤销本连接及其令牌。直播间连接可以跨场次保持；一场直播结束不会自动关闭这个直播间接入。开播、停播及场控操作在工作台完成。