Realtime — 실시간 음성
WebSocket 으로 여는 실시간 세션입니다. 음성 대화와 실시간 받아쓰기를 같은 API 키로 씁니다.
| 용도 | 프로토콜 | 모델 | 주소 |
|---|---|---|---|
| 음성 대화 | OpenAI Realtime | gpt-realtime-2.1, gpt-realtime-2.1-mini | wss://…/v1/gateway/realtime?model=<모델> |
| 음성 대화 | Gemini Live | gemini-3.8-live, gemini-3.8-live-extended-thinking | wss://…/v1/gateway/gemini/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent |
| 음성 대화 | xAI Grok Voice | grok-voice-3.0 | wss://…/v1/gateway/realtime?model=grok-voice-3.0 |
| 음성 대화 | OpenAI Live (GPT-Live) | gpt-live-1 | wss://…/v1/gateway/live/sessions |
| 실시간 받아쓰기 | Soniox | stt-rt-v5 | wss://…/v1/gateway/soniox/transcribe-websocket |
각 제공업체의 원래 프로토콜을 그대로 씁니다. 공식 SDK 나 예제 코드에서 주소와 키만 바꾸면 됩니다. 게이트웨이는 연결마다 인증·과금을 끼워 넣고, 음성 대화 소켓(OpenAI Realtime·xAI Grok Voice·Gemini Live·OpenAI Live)에는 조직이 개인정보 필터를 켠 경우에만 필터를 겁니다. Soniox 소켓에는 필터가 걸리지 않습니다.
음성 대화 모델은 조직에서 켠 경우에만 쓸 수 있습니다.
GET /v1/gateway/models/?type=realtime 에 나오면 쓸 수 있습니다. 실시간 받아쓰기는 파일 받아쓰기(/audio/transcriptions)가 켜진 조직이면 됩니다.인증
인증
서버에서 연결할 때는 WebSocket 핸드셰이크에 키를 헤더로 넣습니다.
Authorization: Bearer, x-api-key, x-goog-api-key 중 무엇이든 됩니다.브라우저에서 연결할 때는 키를 브라우저에 넣지 말고, 서버에서 일회용 토큰을 받아 넘기세요.
POST
/v1/gateway/realtime/sessions/브라우저는
url 에 token 을 쿼리로 붙여 연결합니다 (…?model=gpt-realtime-2.1-mini&token=…, 쿼리가 없는 주소는 ?token=…).- 토큰은 60초 동안, 한 번만 쓸 수 있습니다. 다시 쓰면
1008 invalid or already used session token으로 닫힙니다. - 토큰은 발급할 때 정한 모델에만 쓸 수 있습니다.
model이 채팅 모델이면400과 함께 맞는 엔드포인트를 안내합니다.
OpenAI Realtime
OpenAI Realtime
OpenAI Realtime API 와 같은 이벤트를 주고받습니다. 첫 이벤트로
session.update 를 보내세요.음성으로 주고받으려면
output_modalities 에 audio 를 넣고 input_audio_buffer.append 로 오디오를 보냅니다. 이벤트 전체는 OpenAI Realtime 문서와 같습니다.Gemini Live
Gemini Live
Gemini Live API 와 같은 메시지를 주고받습니다. 연결 후 10초 안에 첫 메시지로
setup 을 보내야 합니다. setup.model 이 쓸 모델입니다. 경로의 버전은 v1beta 와 v1alpha 를 받습니다.xAI Grok Voice
xAI Grok Voice
xAI Voice Agent API 는 OpenAI Realtime 과 같은 이벤트 이름을 쓰므로 같은
/realtime?model= 주소로 엽니다. model=grok-voice-3.0 으로 연결한 뒤 xAI 문서의 이벤트(session.update 의 voice·instructions·turn_detection, input_audio_buffer.append, conversation.item.create, response.create)를 그대로 보냅니다.OpenAI Realtime 과 다른 점:
- 모델은 주소로 정해집니다. 다른
model을 담은session.update에는error이벤트(code: "model_mismatch")가 오고 전달되지 않습니다.reasoning.effort는session.update에 넣고, 주소의 다른 쿼리는 전달되지 않습니다. - xAI 가 실행하는 도구(
web_search,x_search)는 쓸 수 없습니다. 이 도구를 담은session.update·response.create에는error이벤트(code: "unsupported_tool")가 옵니다. 클라이언트가 실행하는function도구와 원격mcp도구는 됩니다.
OpenAI Live (GPT-Live)
OpenAI Live (GPT-Live)
gpt-live-1 은 Realtime 이 아니라 OpenAI Live API 로 동작합니다. /realtime?model=gpt-live-1 로 열면 1008 로 닫히면서 맞는 주소를 알려 줍니다. Live 를 지원하는 OpenAI SDK 에 게이트웨이를 base_url 로 넣으면 SDK 가 <base_url>/live/sessions 로 연결합니다.SDK 없이 연결할 때는
/v1/gateway/live/sessions(쿼리 없음)를 열고, 10초 안에 첫 메시지로 session.start 를 보냅니다. session.model 이 쓸 모델입니다. 끝낼 때는 session.close 를 보내고 session.closed 를 기다리세요. 소켓만 끊으면 게이트웨이가 대신 session.close 를 보냅니다.- 클라이언트 위임만 됩니다.
delegation.type을responses·decisions로 두거나 Decisionstriggers를 쓰면session.start에서는1008로 닫히고,session.update에서는error이벤트(code: "unsupported_delegation")가 옵니다.delegation을 빼거나{"type": "client"}로 두고, 백엔드 에이전트는 직접 실행하세요. - WebRTC·SIP(
POST /v1/live/sessions)와 sideband 소켓은 중계하지 않습니다. - 브라우저용 토큰은
{"model": "gpt-live-1"}로 발급하고, 돌아온url(/v1/gateway/live/sessions)에?token=…을 붙여 연결합니다.
실시간 받아쓰기 (Soniox)
실시간 받아쓰기 (Soniox)
Soniox 실시간 API 와 같습니다. 첫 프레임은 JSON 설정, 그다음은 바이너리 오디오, 끝낼 때는 빈 텍스트 프레임(
"")을 보냅니다. 설정의 api_key 는 넣지 않아도 되고, model 은 stt-rt-v5 로 고정됩니다.끝 프레임을 바이너리(
b"")로 보내면 Soniox 가 끝을 알아채지 못해 잠시 뒤 408 request_timeout 으로 끝납니다.과금
과금
- OpenAI Realtime·Gemini Live 음성 대화는 토큰 단위입니다. 텍스트·오디오 입력과 출력 토큰을 모델 단가로 셉니다(Gemini 는 thinking 토큰 포함).
grok-voice-3.0은 세션 시간(초) 단위에 사용자 텍스트 입력 한 건마다 붙는 요금을 더합니다. 아무도 말하지 않아도 연결된 시간만큼 차감됩니다.gpt-live-1은 세션 시간(초) 단위입니다. 침묵 시간도 포함됩니다.- 실시간 받아쓰기는 처리한 오디오 초 단위입니다.
- 세션을 여는 순간 1분어치를 먼저 잡아 두고, 쓰는 만큼 이어서 잡습니다. 세션이 끝나면 실제로 쓴 만큼만 한 번에 청구됩니다.
- 사용량은
/usage에 모델 이름으로 남습니다.
연결이 닫힐 때
연결이 닫힐 때
거절은 모두 연결을 연 뒤 닫힘 코드로 알려 줍니다. 닫힘 사유(reason)에 원인이 적혀 있습니다.
| 코드 | 뜻 | 대표 사유 |
|---|---|---|
1000 | 정상 종료 — 세션당 60분 상한에 닿은 경우 포함 | session cap, upstream closed, client closed |
1008 | 정책 위반 — 인증 실패, 모델 없음·꺼짐, 잘못된 첫 메시지 | missing ?model= on the URL, setup message not received in time, invalid or already used session token |
1011 | 서버·제공업체 오류 — 제공업체 쪽이 비정상적으로 연결을 닫은 경우 포함 | Gemini Live unavailable, upstream closed <code>: <제공업체 사유> |
1013 | 잠시 후 다시 — 실시간 받아쓰기 동시 세션이 꽉 찼거나, 연결 시 검사가 429/503(속도 제한, 일시적 사용 불가)으로 응답함 | all realtime slots are busy, retry shortly, 또는 해당 429/503 메시지 |
4402 | 크레딧 부족 | 세션을 열 때나 도중에 잔액이 모자라면 이 코드로 닫힙니다 (insufficient credits) |
마지막 수정 날짜: Nov 18, 2026

