> 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 > 수명이 짧은 실시간 API 브라우저 세션을 만들고 BeatAPI 실시간 SDK용 클라이언트 시크릿을 받습니다. `POST https://api.beatapi.io/v1/realtime/sessions` 수명이 짧은 실시간 API 브라우저 세션을 만들고 BeatAPI 실시간 SDK용 클라이언트 시크릿을 받습니다. ## 인증 `Authorization`   `string`   **필수** BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 [대시보드](https://beatapi.io/dashboard)에서 만들 수 있습니다. ``` Authorization: Bearer ``` 영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 `Content-Type: application/json`이 필요합니다. `Idempotency-Key`는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다. ## 요청 본문 `max_duration_seconds`   `enum`   **필수** 필수인 라이브 세션 최대 길이(초)입니다. 선택한 15, 60 또는 300초 등급의 USD 금액이 보류됩니다. **사용 가능한 옵션:** `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`). 계정 잔액이 0이거나 이 요청의 가격보다 적습니다. 충전한 뒤 다시 보내세요. 충전 전에는 재시도할 수 없습니다. | | `409` | `Idempotency-Key`가 24시간 안에 다른 요청 본문이나 경로에 이미 사용되었거나, 이 키를 사용한 첫 요청이 아직 처리 중입니다(`idempotency_conflict`). 그대로 재시도할 수 없습니다. | | `429` | 요청이 너무 많습니다(`rate_limit_exceeded`, 무료 모델 한도 포함). `Retry-After`(또는 `error.retry_after_seconds`)에 표시된 초만큼 기다린 뒤 재시도할 수 있습니다. | | `503` | 이 배포 환경에서 Realtime Video가 활성화되어 있지 않거나(`realtime_disabled`, 재시도 불가. 직접 조치할 방법이 없으니 지원팀에 문의) 용량을 일시적으로 사용할 수 없습니다(`realtime_capacity_unavailable`, 재시도 가능. 잠시 후 백오프를 두고 재시도하며 대기 시간은 표시되지 않음). |