> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # リアルタイム API > 有効期間の短い Realtime API のブラウザーセッションを作成し、BeatAPI リアルタイム SDK 用の client secret を取得します。 `POST https://api.beatapi.io/v1/realtime/sessions` 有効期間の短い Realtime API のブラウザーセッションを作成し、BeatAPI リアルタイム SDK 用の client secret を取得します。 ## 認証 `Authorization`   `string`   **必須** BeatAPI の API キーを Bearer トークンとして送信します。API キーは[ダッシュボード](https://beatapi.io/dashboard)で作成できます。 ``` Authorization: Bearer ``` 通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには `Content-Type: application/json` が必要です。対応するエンドポイントでは `Idempotency-Key` は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。 ## リクエストボディ `max_duration_seconds`   `enum`   **必須** ライブセッションの最大継続時間を秒単位で指定します。必須フィールドです。選択した 15 秒・60 秒・300 秒の区分に対応する米ドル建て料金が仮確保されます。 **選択肢:** `15`, `60`, `300` --- `allowed_origins`   `string[]`   **必須** 短期セッションのシークレットの使用を許可する、ブラウザーのオリジンです。完全一致する値を指定してください。 **要素数:** 1 – 10 件 --- `metadata`   `object`   **任意** 自社システムのデータと関連付けるため、サーバー側で定義する任意の文字列メタデータです。最大 20 キーで、キーは最大 64 文字、値は最大 256 文字です。 ## レスポンス リクエストが成功すると、HTTP `201` が返されます。 ```json { "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 をインストールします。 ```bash npm install @beatapi/realtime ``` ```ts import { createRealtimeClient } from '@beatapi/realtime'; const camera = await navigator.mediaDevices.getUserMedia({ video: true }); const output = document.querySelector('#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 キーは信頼できるサーバーで管理し、ブラウザーでの利用が終わったらセッションを終了してください。 ## エラー | ステータスコード | 意味と対処方法 | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | JSON の形式が不正、またはフィールド・値・組み合わせが未対応です（`bad_request`。メッセージにフィールド名が記載されます）。入力がコンテンツ審査で拒否された場合は `content_policy_violation` です。修正せずに再試行しても成功しません。 | | `401` | API キーが未指定（`missing_api_key`）、またはキーが不正・期限切れ・無効・上限到達です（`invalid_api_key`。理由はメッセージに記載されます）。`Authorization: Bearer ` で送信してください。`sk-` 接頭辞の有無にかかわらず使えます。そのまま再試行しないでください。 | | `402` | 残高不足です（`insufficient_credits`）。残高がゼロ、またはこのリクエストの料金に足りません。残高をチャージしてから再度送信してください。それまでは再試行しないでください。 | | `409` | `Idempotency-Key` が別のリクエストボディで使用済み、または同じキーの最初のリクエストが処理中です（`idempotency_conflict`）。そのまま再試行しないでください。 | | `429` | リクエスト数が上限を超えています（無料モデルの制限を含む `rate_limit_exceeded`）、または同時処理中のタスクが多すぎます（`user_concurrency_exceeded`）。`Retry-After` の秒数だけ待ってから再試行できます。同じ値は `error.retry_after_seconds` にも含まれます。 | | `503` | このアカウントではリアルタイム機能が無効です（`realtime_disabled`、再試行不可）、または処理枠が一時的に不足しています（`realtime_capacity_unavailable`、`Retry-After` の秒数だけ待って再試行可能）。 |