실시간 API

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

수명이 짧은 실시간 API 브라우저 세션을 만들고 BeatAPI 실시간 SDK용 클라이언트 시크릿을 받습니다.

인증

Authorization   string   필수

BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 대시보드에서 만들 수 있습니다.

Authorization: Bearer <BEATAPI_API_KEY>

영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 Content-Type: application/json이 필요합니다. Idempotency-Key는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다.

요청 본문

max_duration_seconds   enum<integer>   필수

필수인 라이브 세션 최대 길이(초)입니다. 선택한 15, 60 또는 300초 등급의 USD 금액이 보류됩니다.

사용 가능한 옵션: 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 키는 신뢰할 수 있는 서버에 두고, 브라우저 사용이 끝나면 세션을 닫으세요.

오류