WebRTC Relay API v1

{
  "device_ip": "192.168.1.10",
  "device_tcp_port": 30007,
  "device_udp_port": 30008,
  "quality": 720,
  "codec": "h264"
}

{
  "code": 0,
  "data": {
    "session_id": "abc123",
    "proxy_tcp_port": 3478,
    "proxy_udp_port": 3478,
    "play_url": "/player.html?session_id=s_abc123&token=t_xxx",
    "orientation": "portrait",
    "created_at": "2026-04-07T12:00:00Z",
    "preempted_session": null
  }
}

{
  "session_id": "你的会话ID"
}

{
  "code": 0,
  "message": "session closed"
}

{
  "code": 0,
  "data": {
    "session_id": "abc123",
    "device_ip": "192.168.1.10",
    "status": "active",
    "idle_seconds": 12,
    "heartbeat_status": "healthy",
    ...
  }
}

{
  "code": 0,
  "data": {
    "total": 5,
    "sessions": [ ... ]
  }
}

{
  "session_id": "你的会话ID",
  "orientation": "portrait"   // 或 "landscape"
}

{
  "code": 0,
  "message": "orientation updated",
  "data": { "session_id": "...", "orientation": "portrait" }
}

{
  "session_id": "你的会话ID",
  "command": "goHome"
}

{
  "code": 0,
  "data": { "commands": ["goHome", "volUp"] }
}

{
  "session_id": "你的会话ID",
  "quality": 720    // 可选值: 480, 720, 1080
}

{
  "code": 0,
  "data": {
    "uptime": "2h30m",          // 运行时长
    "goroutines": 42,            // 协程数
    "memory": {                  // 内存使用
      "alloc_mb": "12.34",
      "total_alloc_mb": "56.78",
      "sys_mb": "30.00",
      "gc_count": 15
    },
    "port_pool": {               // 端口池
      "total": 20,
      "used": 3,
      "available": 17,
      "usage_percent": "15.00"
    },
    "devices": {                 // 设备统计
      "active_devices": 3,
      "proxy_connections": 6,
      "stale_devices": 0
    },
    "traffic": {                 // 流量统计
      "active_forwarded_bytes": 1048576,
      "throughput_bps": "524288.00"
    },
    "startup": {                 // 启动失败
      "recent_failures": 0,
      "last_failure_time": null,
      "last_failure_reason": ""
    },
    "contention": {              // 竞争统计
      "total_count": 0,
      "last_minute_count": 0,
      "frequent_devices": []
    }
  }
}

{
  "code": 0,
  "message": "contentions cleared"
}

{
  "session_ids": ["s_abc123", "s_def456"]
}

{
  "code": 0,
  "data": {
    "group_id": "g_98b16c56bf523c7e",
    "members": ["s_abc123", "s_def456"],
    "created_at": "2026-04-07T12:00:00Z"
  }
}

{
  "group_id": "g_98b16c56bf523c7e",
  "session_id": "s_newmember"
}

{
  "code": 0,
  "message": "joined group"
}

{
  "code": 0,
  "message": "left group"
}

最后一个成员离开时群组自动解散。

{
  "code": 0,
  "message": "group disbanded"
}

{
  "code": 0,
  "data": {
    "group_id": "g_98b16c56bf523c7e",
    "members": ["s_abc123", "s_def456", "s_ghi789"],
    "member_count": 3,
    "created_at": "2026-04-07T12:00:00Z"
  }
}

{
  "code": 0,
  "data": {
    "total": 1,
    "groups": [{
      "group_id": "g_98b16c56bf523c7e",
      "members": ["s_abc123", "s_def456"],
      "member_count": 2,
      "created_at": "2026-04-07T12:00:00Z"
    }]
  }
}

WebSocket 连接，用于实时同步群组内的操作事件。每个成员建立一个连接，既发送又接收。

ws://host/api/v1/group/ws?session_id=s_abc123

// SDK 触摸事件（由 fun_send_data 发出）
{"t":1, "d":{"mx":360,"my":640,"sw":720,"sh":1280,...}}

// 控制按钮（home/back/volUp 等）
{"_groupCmd":true, "command":"goHome"}

1. 调用 /api/v1/group/create 创建群组并传入所有 session_id
2. 每个设备的 iframe 通过 postMessage 发送 start-group-peer 消息启动 peer 模式
3. 后续加入的设备调用 /api/v1/group/join 后同样启动 peer 模式
4. 操作任意设备，其余设备自动同步

Go 壳播放器通常会自动调用这个接口。它根据 session_id 和 token 返回固定端口播放所需的运行时参数，前端一般不需要手动拼接 shost、rtc_i、sport、rtc_p。

{
  "code": 0,
  "data": {
    "session_id": "s_abc123",
    "token": "t_xxx",
    "shost": "relay.example.com",
    "sport": 3478,
    "rtc_i": "relay.example.com",
    "rtc_p": 3478,
    "q": 2,
    "v": "h264",
    "sw": 1280,
    "sh": 720,
    "tshow": 0
  }
}

const BASE = '';  // 同源，留空即可

// 1. 创建会话
const res = await fetch(BASE + '/api/v1/session/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    device_ip: '192.168.1.10',
    device_tcp_port: 30007,
    device_udp_port: 30008,
    quality: 720,
    codec: 'h264'
  })
});
const { data } = await res.json();
const sessionId = data.session_id;

// 2. 嵌入播放器 iframe
document.getElementById('myPlayer').src = data.play_url;

// 3. 发送设备指令
await fetch(BASE + '/api/v1/session/command', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    session_id: sessionId,
    command: 'goHome'
  })
});

// 4. 查询系统状态
const stats = await fetch(BASE + '/api/v1/stats').then(r => r.json());
console.log(stats.data);

// 5. 关闭会话
await fetch(BASE + '/api/v1/session/close', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ session_id: sessionId })
});

# 创建会话（返回 play_url）
curl -X POST https://relay.example.com/api/v1/session/create \
  -H "Content-Type: application/json" \
  -d '{"device_ip":"192.168.1.10","device_tcp_port":30007,"device_udp_port":30008,"quality":720,"codec":"h264"}'

# 拿到 play_url 后在浏览器打开即可播放，例如:
# https://relay.example.com/player.html?session_id=s_abc123&token=t_xxx

# 获取会话列表
curl https://relay.example.com/api/v1/sessions

# 发送设备指令
curl -X POST https://relay.example.com/api/v1/session/command \
  -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_ID","command":"goHome"}'

# 查询系统状态
curl https://relay.example.com/api/v1/stats

# 关闭会话
curl -X POST https://relay.example.com/api/v1/session/close \
  -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_ID"}'

import requests

BASE = "https://relay.example.com"

# 创建会话
r = requests.post(f"{BASE}/api/v1/session/create", json={
    "device_ip": "192.168.1.10",
    "device_tcp_port": 30007,
    "device_udp_port": 30008,
    "quality": 720,
    "codec": "h264"
})
data = r.json()["data"]
session_id = data["session_id"]
play_url = data["play_url"]

# play_url 就是播放地址，拼接完整 URL 后可在浏览器打开
full_url = f"{BASE}{play_url}"
print(f"播放地址: {full_url}")

# 发送设备指令
requests.post(f"{BASE}/api/v1/session/command", json={
    "session_id": session_id,
    "command": "goHome"
})

# 查询系统状态
stats = requests.get(f"{BASE}/api/v1/stats").json()

# 关闭会话
requests.post(f"{BASE}/api/v1/session/close", json={
    "session_id": session_id
})

import java.net.http.*;
import java.net.URI;
import com.google.gson.*;

String BASE = "https://relay.example.com";
HttpClient client = HttpClient.newHttpClient();
Gson gson = new Gson();

// 1. 创建会话
String body = gson.toJson(Map.of(
    "device_ip", "192.168.1.10",
    "device_tcp_port", 30007,
    "device_udp_port", 30008,
    "quality", 720,
    "codec", "h264"
));

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/api/v1/session/create"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
JsonObject data = gson.fromJson(res.body(), JsonObject.class)
    .getAsJsonObject("data");

String sessionId = data.get("session_id").getAsString();
String playUrl = data.get("play_url").getAsString();

// 2. 拼接完整播放地址，传给前端
String fullPlayUrl = BASE + playUrl;
// 前端拿到这个 URL 放进 iframe 或 window.open() 即可播放

// 3. 关闭会话
String closeBody = gson.toJson(Map.of("session_id", sessionId));
HttpRequest closeReq = HttpRequest.newBuilder()
    .uri(URI.create(BASE + "/api/v1/session/close"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(closeBody))
    .build();
client.send(closeReq, HttpResponse.BodyHandlers.ofString());