实时 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–255 个字符；只有完全相同的请求体才能安全复用原键。

请求体

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

max_duration_seconds   enum<integer>   必填

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

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

allowed_origins   string[]   必填

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

取值与默认值: 1–10 项

metadata   object   选填

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

响应

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

{
  "data": {
    "id": "rts_8K2qA",
    "object": "realtime.session",
    "status": "ready",
    "client_secret": "brt_live_example_short_lived_secret",
    "expires_at": "2026-08-12T10:01:00.000Z",
    "max_duration_seconds": 60,
    "allowed_origins": [
      "https://app.example.com"
    ],
    "credits": {
      "reserved": 1.2,
      "settled": 0,
      "refunded": 0
    },
    "request_id": "req_abc123",
    "created_at": "2026-08-12T10:00:00.000Z",
    "connected_at": null,
    "closed_at": null
  }
}

在浏览器中连接

安装实时 SDK。

npm install @beatapi/realtime

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

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

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

下一步

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

错误