文档目录

开放接口

本页内容

地址与格式
认证
查看令牌能用的接口
设备
实时画面
安全提示

Rerinku View 提供一套开放的 HTTP 接口，网页、服务端程序和 App 都可以直接调用。网页里推荐用 Web SDK，它把认证、信令和重连都处理好了；这一页介绍接口本身，适合其他语言或自己实现客户端的场景。

地址与格式

基址就是 Rerinku View 的地址：局域网地址（如 http://192.168.1.10:8080），或开了快速连接时的快速连接地址。设置 → 开发者 页面列出了可用的地址。所有接口都在 /api/v1/ 下。
成功响应统一包一层 data：{ "data": ... }。二进制和媒体响应（JPEG、SDP）不包。
错误响应统一为 { "error": { "message": "...", "code": "..." } }。请按 HTTP 状态码处理；需要区分的错误（认证、实时流信令）会带机器可读的 code。
请求体不允许多余字段：多传一个字段会返回 400。
时间一律是 RFC 3339。

认证

请求头带上令牌：

Authorization: Bearer <令牌>

令牌	怎么获得	能做什么
只读查看令牌	在控制台设置 → 开发者里生成，只能在控制台里生成	只能调用下表中的几个接口，可以放进公开网页
完整令牌	`POST /api/v1/auth/bind`（和手机 App 一样绑定）	与该绑定对应的完整权限

所有令牌都列在 设置 → 开发者 → 已授权的应用（GET /api/v1/clients）里，可以随时撤销（DELETE /api/v1/clients/{id}）。撤销后请求返回 401，code 为 invalid_token。

跨域规则

任何网站都可以跨域调用，不用设访问密码，也不用登记来源（CORS 对所有来源放行，不发送 Allow-Credentials）。唯一的硬规则是：来自别的网站的请求必须带令牌，否则访客打开的任意网页都能借他的浏览器操作你局域网里的 Rerinku View。

来自别的网站的请求	结果
`GET /api/v1/auth/info`	照常，不需要令牌
`POST /api/v1/auth/bind`	Rerinku View 设了访问密码：照常（由 bind 校验密码）；没设：`403`，`code` 为 `cross_site_bind`
其余 `/api/v1/*`	带有效令牌照常；不带则 `401`，`code` 为 `authentication_required`

服务端程序和原生 App 不发送 Origin 请求头，不受这条规则约束。它们要不要令牌取决于 Rerinku View 的监听地址：只监听本机回环时不需要，监听局域网地址（默认）时需要。

绑定换取完整令牌

POST /api/v1/auth/bind
Content-Type: application/json

{ "password": "", "name": "门店看板", "platform": "sdk", "device_id": "dash-0001", "app_version": "1.0" }

{ "data": { "access_token": "<令牌>", "token_type": "Bearer" } }

password：Rerinku View 的访问密码，没设就传空串。
device_id：你自己生成并长期保存的安装 ID（8–64 位字母、数字或 -）。同一个 ID 再次绑定只换新令牌，不会多出一条授权。
密码错误返回 401（invalid_password），尝试太频繁返回 429（too_many_attempts）。

查看令牌能用的接口

接口	说明
`GET /api/v1/devices`	设备列表。查看令牌拿到的是脱敏后的字段：没有地址、MAC、序列号、硬件 ID、录像和云台配置
`GET /api/v1/devices/{id}/streams`	设备的码流目录
`GET /api/v1/devices/{id}/thumbnail`	最近一帧缩略图（JPEG）
`GET /api/v1/devices/{id}/runtime`	设备此刻的运行状态，只有用 Rerinku View SDK 接入的设备能回答
`POST /api/v1/devices/{id}/live`、`POST /api/v1/devices/{id}/streams/{stream}/live`	拉实时画面（WebRTC）
`GET /api/v1/ice-servers`	实时画面用的 STUN/TURN 配置

其余接口对查看令牌一律返回 403，code 为 insufficient_scope。完整令牌能用的接口更多，见 Rerinku View 仓库的 docs/API.md。

设备

GET /api/v1/devices

{
  "data": [
    {
      "id": 3,
      "sn": "0123456789ABCDEF",
      "name": "前门",
      "protocol": "onvif",
      "group": "一楼",
      "online": true,
      "streaming": false,
      "stream_kind": "webrtc",
      "video_codec": "H265",
      "has_thumbnail": true,
      "streams": [
        {
          "id": "main",
          "name": "主码流",
          "default": false,
          "tracks": [{ "kind": "video", "codec": "H265" }]
        },
        { "id": "sub", "name": "子码流", "default": true, "tracks": [{ "kind": "video", "codec": "H264" }] }
      ]
    }
  ]
}

stream_kind 为 unsupported 时，浏览器无法播放这台设备的画面。
streams 是设备的各路码流；default: true 的那一路，是不指定码流时播放的。
用 Rerinku View SDK 接入的设备还会带 ext：设备自报的静态信息（SoC、CPU、内存、传感器……）。

GET /api/v1/devices/{id}/runtime 返回设备此刻的状态：

{
  "data": {
    "supported": true,
    "online": true,
    "at": 1793000000000,
    "values": { "tempC": 63.6, "cpuPct": 11.2 }
  }
}

平台每次都会实时询问设备，同一台设备 2 秒内复用结果，轮询请不要比这更快。

实时画面

实时画面是一次性的 SDP 交换，与 WHEP 的做法相同：

GET /api/v1/ice-servers 取 STUN/TURN 配置，用它创建 RTCPeerConnection（TURN 凭据会过期，每次连接前都取一次）。
添加只接收（recvonly）的视频和音频收发器，生成 offer，等 ICE 收集完成。
把 offer 作为请求体 POST 过去，拿回 answer：

POST /api/v1/devices/{id}/streams/{stream}/live
Content-Type: application/sdp
Authorization: Bearer <令牌>

<SDP offer 原文>

成功返回 201，Content-Type: application/sdp，响应体是 SDP answer 原文。不带 /streams/{stream} 时播放默认码流。

状态码	含义	建议
`404`	设备或码流不存在	不要重试
`409`	设备离线（`code`：`device_offline`）	慢一点重试，比如每 15 秒一次
`422`	offer 有问题，或这种接入方式不支持选择码流	不要重试
`408`、`504`	信令超时、设备没有响应启流	可以重试
`502`、`503`	设备侧或服务暂时不可用	退避重试

连接断开后，用同一个地址重新交换一次即可。Web SDK 的重连策略就是按这张表实现的。

安全提示

公开网页里会写着 Rerinku View 的地址。查看令牌只限制带着它的请求：如果那台 Rerinku View 没设访问密码，知道地址的人可以直接打开控制台（用 curl 之类的工具也能伪造浏览器的同源请求），查看令牌的限制挡不住他们，快速连接地址本身就相当于钥匙。用来放公开演示的 Rerinku View，请设置访问密码，或打开演示模式（DEMO_MODE）让所有人只能看、不能改。另外，接了快速连接时，/api/v1/ice-servers 返回的是本节点的 TURN 凭据（24 小时有效），公开出去可能被拿去使用中继。