リアルタイム API

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

有効期間の短い Realtime API のブラウザーセッションを作成し、BeatAPI リアルタイム SDK 用の client secret を取得します。

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

max_duration_seconds   enum<integer>   必須

ライブセッションの最大継続時間を秒単位で指定します。必須フィールドです。選択した 15 秒・60 秒・300 秒の区分に対応する米ドル建て料金が仮確保されます。

選択肢: 15, 60, 300

allowed_origins   string[]   必須

短期セッションのシークレットの使用を許可する、ブラウザーのオリジンです。完全一致する値を指定してください。

要素数: 1 – 10 件

metadata   object   任意

自社システムのデータと関連付けるため、サーバー側で定義する任意の文字列メタデータです。最大 20 キーで、キーは最大 64 文字、値は最大 256 文字です。

レスポンス

リクエストが成功すると、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: 'Preserve motion while applying the requested style.' },
});

短期の client_secret だけを、allowed_origins に記載した完全一致のオリジンへ渡してください。選択した継続時間の料金は作成時に仮確保されます。最初のリモート出力フレームにより、BeatAPI が受理する課金ハートビートが発生した後にのみ精算されます。

• GET /v1/realtime/sessions/{session_id}：リアルタイムセッションの情報を取得します。
• DELETE /v1/realtime/sessions/{session_id}：リアルタイムセッションを終了します。

利用が終わったらブラウザーの接続を切り、ローカルのメディアトラックを停止し、サーバー側のセッションも終了してください。

次の手順

返された client_secret を @beatapi/realtime に渡します。通常の API キーは信頼できるサーバーで管理し、ブラウザーでの利用が終わったらセッションを終了してください。

エラー