Realtime
OpenAI Realtime API 호환 음성 WebSocket.
WS /v1/realtime은 OpenAI Realtime 이벤트를 투명 프록시합니다. base URL과 API 키만 바꾸면 서버-투-서버 WebSocket 클라이언트가 동작합니다.
WS/v1/realtime
인증#
핸드셰이크에 Authorization: Bearer plm_… 또는 x-api-key를 넣으세요. 쿼리 스트링에 키를 넣지 마세요.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | query | 필수 | gpt-realtime-2.1 또는 gpt-realtime-2.1-mini |
| Authorization | header | 필수 | Bearer plm_… 또는 x-api-key |
연결 및 세션 흐름#
연결이 열리면 session.update로 modalities와 voice 등 세션을 설정하고 Realtime 이벤트를 주고받습니다. 서버 이벤트는 그대로 전달됩니다. response.done 사용량을 모아 연결 종료 때 정산합니다.
Node.js 예시#
Node.js 예시
import WebSocket from "ws";
const model = "gpt-realtime-2.1";
const url = `wss://apirouter.pleum.ai/v1/realtime?model=${model}`;
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.PLEUM_API_KEY,
},
});
ws.on("open", () => {
ws.send(JSON.stringify({
type: "session.update",
session: { modalities: ["audio", "text"], voice: "alloy" },
}));
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
console.log(event.type);
});연결 오류와 복구#
종료 코드
1008은 지원하지 않는 모델·누락/잘못된 키·키 권한을 확인하세요. 1013은 요청 한도 초과이므로 호출 빈도를 낮춘 뒤 다시 연결하세요. 1011은 provider key 또는 업스트림 연결 문제입니다. 원인을 확인하고 다시 연결하세요.과금과 제한#
세션 연결 시 크레딧을 hold하고, response.done usage(text/audio 토큰)를 누적한 뒤 종료 시 settle합니다. 업스트림 세션이 성공하면 최소 1 최소단위가 청구됩니다(실시간 세션은 고정가 계약이라 정수 단위).
세션 최대 25분 · idle 5분 · 연결 후 첫 클라이언트 메시지 30초.