实时 API

POST https://api.beatapi.io/v1/realtime/sessions

创建短期实时浏览器会话，并获取 BeatAPI 实时 SDK 使用的 client_secret。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。此接口必须为每个逻辑创建请求设置唯一的 Idempotency-Key，长度为 1–128 个字符；只有完全相同的请求体才能安全复用原键。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

max_duration_seconds   enum<integer>   必填

该实时会话允许的最长持续时间，单位为秒，也是预留费用的档位。

取值与默认值: 可选值 15、60、300

allowed_origins   string[]   必填

允许使用短期会话密钥的完整浏览器来源列表。生产环境应使用 HTTPS。

取值与默认值: 1–10 项

metadata   object   选填

用于业务关联的自定义字符串元数据。

响应

成功请求返回 HTTP 201，响应体如下。

1
{
2
  "data": {
3
    "id": "rts_8K2qA",
4
    "object": "realtime.session",
5
    "status": "ready",
6
    "client_secret": "brt_live_example_short_lived_secret",
7
    "expires_at": "2026-08-12T10:01:00.000Z",
8
    "max_duration_seconds": 60,
9
    "allowed_origins": [
10
      "https://app.example.com"
11
    ],
12
    "credits": {
13
      "reserved": 1.2,
14
      "settled": 0,
15
      "refunded": 0
16
    },
17
    "request_id": "req_abc123",
18
    "created_at": "2026-08-12T10:00:00.000Z",
19
    "connected_at": null,
20
    "closed_at": null
21
  }
22
}

在浏览器中连接

安装实时 SDK。

$
npm install @beatapi/realtime

1
import { createRealtimeClient } from '@beatapi/realtime';
2
3
const camera = await navigator.mediaDevices.getUserMedia({ video: true });
4
const output = document.querySelector<HTMLVideoElement>('#output')!;
5
const client = createRealtimeClient({ clientSecret: session.client_secret });
6
const connection = await client.connect({
7
  input: camera,
8
  output,
9
  initial: { prompt: '保留动作，同时应用指定风格。' },
10
});

只能把短期 client_secret 交给 allowed_origins 中完全匹配的来源。体验结束后，请断开浏览器连接、停止本地媒体轨道，并关闭服务端会话。

• GET /v1/realtime/sessions/{session_id}：查询实时会话。
• DELETE /v1/realtime/sessions/{session_id}：关闭实时会话。

下一步

将返回的 client_secret 交给 @beatapi/realtime。永久 API 密钥必须保存在可信服务端，浏览器体验结束后请关闭会话。

错误