실시간 음성 (Realtime)

소개

WebSocket을 통해 저지연 실시간 음성 세션을 구성합니다. OpenAI Realtime API와 호환됩니다. 연결 후 이벤트 프로토콜로 오디오와 텍스트를 주고받으며, 음성 비서, 실시간 번역 등에 적합합니다. Base URL: wss://api.gravitex.ai/v1/realtime

일반 HTTP POST가 아닌 WebSocket 프로토콜을 사용해야 합니다. model은 쿼리 파라미터로 전달해야 하며, 그렇지 않으면 게이트웨이가 400을 반환합니다.

인증

WebSocket 연결 시 다음 헤더를 포함합니다:

string

필수

Bearer 토큰, 예: Bearer sk-xxxxxxxxxx

string

필수

realtime=v1 고정

브라우저에서는 WebSocket 헤더를 직접 설정할 수 없습니다. OpenAI 서브프로토콜로 키를 전달할 수 있습니다(헤더 방식과 동등, 게이트웨이에서 파싱):

Sec-WebSocket-Protocol: realtime, openai-insecure-api-key.sk-xxxxxxxxxx, openai-beta.realtime-v1

연결

wss://api.gravitex.ai/v1/realtime?model=gpt-realtime-1.5

string

필수

실시간 모델 ID, 예: gpt-realtime-1.5, gpt-realtime-2. 현재 API Key에서 사용 가능한 모델과 일치해야 합니다.

연결 성공 시 서버는 101 Switching Protocols를 반환합니다. 이후 session.created를 수신하면 session.update를 전송해 세션을 구성합니다.

세션 구성

연결 후 session.update로 지시문, 출력 모달리티, 오디오 형식을 설정합니다:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "You are a concise assistant. Reply in Chinese. 回答用中文回答",
    "output_modalities": ["audio"],
    "audio": {
      "input":  { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 }, "voice": "sage" }
    }
  }
}

필드	설명
`session.type`	항상 `realtime`
`instructions`	시스템 지시문, 어시스턴트 동작 및 응답 언어 제어
`output_modalities`	`["audio"]` 음성 출력; `["text"]` 텍스트만 출력(오디오 재생 없음)
`audio.input.format`	입력 오디오 형식: PCM16, 24 kHz, 모노
`audio.output.format`	출력 오디오 형식: 위와 동일
`audio.output.voice`	음색, 아래 선택값 참고

선택 가능한 음색 (output_modalities에 audio 포함 시): alloy · ash · ballad · coral · echo · sage · shimmer · verse · marin session.updated를 수신한 후 대화를 시작합니다.

메시지 전송

각 턴은 두 단계로 구성됩니다:

conversation.item.create — 사용자 메시지 작성
response.create — 모델 응답 생성 트리거

텍스트 입력

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      { "type": "input_text", "text": "안녕하세요, 중국어로 자기소개해 주세요" }
    ]
  }
}

오디오 입력

녹음은 PCM16 raw bytes(WAV 헤더 없음)여야 하며 Base64로 인코딩해 전송합니다:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      { "type": "input_audio", "audio": "<base64_pcm16>" }
    ]
  }
}

한 턴에 여러 입력을 조합할 수 있습니다. 예: 이미지 + 텍스트, 이미지 + 녹음:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      { "type": "ms_image", "image": "data:image/jpeg;base64,<base64>" },
      { "type": "input_text", "text": "이 이미지에 무엇이 있나요?" }
    ]
  }
}

이미지 입력 제한: 일부 업스트림(예: Azure OpenAI Realtime)은 이미지를 지원하지 않으며 input_text와 input_audio만 지원합니다. 이미지 전송 시 서버 500 오류가 발생할 수 있습니다. Vision 기능은 Realtime이 아닌 Chat Completions / Responses API에서만 사용 가능합니다. Microsoft 공식 설명 참고. Base64 이미지 길이는 1,048,576자(원본 약 750 KB) 이하 권장.

메시지 작성 후 응답을 트리거합니다:

{ "type": "response.create" }

응답 수신

일반적인 서버 이벤트:

이벤트 유형	설명
`response.text.delta` / `response.output_text.delta`	텍스트 응답 증분 (`output_modalities: ["text"]`)
`response.audio_transcript.delta` / `response.output_audio_transcript.delta`	오디오 응답의 텍스트 전사 증분
`response.audio.delta` / `response.output_audio.delta`	PCM16 오디오 증분(Base64), 디코딩 후 재생
`response.done`	해당 턴 종료, `usage` 포함
`error`	오류; 일부 업스트림 오류 후 연결이 종료되므로 재연결 필요

오디오 증분 필드는 audio 또는 delta일 수 있으므로 클라이언트는 둘 다 처리해야 합니다.

사용량

각 response.done은 해당 Response의 사용량만 반환하며, 세션 누적이 아닙니다. 공식 문서: “The tokens used for a Response can be read from the response.done event”. 다중 턴 대화에서는 턴별 사용량과 세션 누적 사용량을 함께 기록하는 것을 권장합니다. usage 구조 예시:

{
  "total_tokens": 320,
  "input_tokens": 180,
  "output_tokens": 140,
  "input_token_details": {
    "text_tokens": 50,
    "audio_tokens": 130,
    "image_tokens": 0,
    "cached_tokens": 20,
    "cached_tokens_details": {
      "text_tokens": 8,
      "audio_tokens": 12
    }
  },
  "output_token_details": {
    "text_tokens": 40,
    "audio_tokens": 100
  }
}

필드 설명

필드	설명
`total_tokens`	`input_tokens` + `output_tokens`
`input_tokens`	모델에 전송된 전체 입력(대화 기록 포함)
`input_token_details.text_tokens`	입력의 텍스트 토큰
`input_token_details.audio_tokens`	입력의 오디오 토큰
`input_token_details.image_tokens`	입력의 이미지 토큰
`input_token_details.cached_tokens`	`input_tokens`의 부분집합(추가 합산이 아님), prompt cache 히트 부분; 캐시 가격으로 과금
`cached_tokens_details.text_tokens`	캐시 중 텍스트 부분(OpenAI 네이티브 반환)
`cached_tokens_details.audio_tokens`	캐시 중 오디오 부분(OpenAI 네이티브 반환)
`output_tokens`	해당 턴 생성 토큰
`output_token_details.text_tokens`	출력의 텍스트 토큰, 즉 오디오 응답 transcript
`output_token_details.audio_tokens`	출력의 오디오 토큰

output.text_tokens: 오디오 출력을 선택해도 자동 transcript로 텍스트 토큰이 발생하며, 정상 과금입니다. OpenAI Realtime 과금 참고.
input.cached_tokens: input_tokens의 부분집합이며 추가 합산이 아닙니다. OpenAI는 cached_tokens_details(텍스트/오디오 분리)를 반환하고, 일부 업스트림(예: Azure GA)이 반환하지 않으면 게이트웨이가 텍스트/오디오 입력 비율로 추정합니다.
다중 턴 비용: 각 Response는 전체 대화 기록을 전송하므로 턴이 진행될수록 input_tokens가 커집니다. 초기 턴은 prompt cache에 히트할 가능성이 높아 할인율이 큽니다(예: gpt-realtime-2 오디오 캐시 $0.40/1M, 오디오 입력$ 32/1M 대비 98.75% 할인). 공식 문서: “turns later in the session will be more expensive”.

Python 전체 예제

의존성: pip install websockets pyaudio

import asyncio
import base64
import json
import websockets

BASE_URL = "wss://api.gravitex.ai/v1/realtime"
API_KEY  = "sk-xxxxxxxxxx"
MODEL    = "gpt-realtime-1.5"

async def main():
    url = f"{BASE_URL}?model={MODEL}"

    async with websockets.connect(url, additional_headers={
        "Authorization": f"Bearer {API_KEY}",
        "OpenAI-Beta": "realtime=v1",
    }) as ws:
        # 1. 세션 구성
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "instructions": "You are a concise assistant. Reply in Chinese.",
                "output_modalities": ["audio"],
                "audio": {
                    "input":  {"format": {"type": "audio/pcm", "rate": 24000}},
                    "output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "sage"},
                },
            },
        }))

        # 2. 세션 준비 대기
        async for raw in ws:
            evt = json.loads(raw)
            if evt.get("type") in ("session.created", "session.updated"):
                break

        # 3. 텍스트 전송 및 응답 트리거
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "message",
                "role": "user",
                "content": [{"type": "input_text", "text": "안녕하세요"}],
            },
        }))
        await ws.send(json.dumps({"type": "response.create"}))

        # 4. 응답 수신
        async for raw in ws:
            evt = json.loads(raw)
            t = evt.get("type", "")
            if t in ("response.text.delta", "response.output_text.delta",
                     "response.audio_transcript.delta", "response.output_audio_transcript.delta"):
                print(evt.get("delta", ""), end="", flush=True)
            elif t in ("response.audio.delta", "response.output_audio.delta"):
                audio_b64 = evt.get("audio", "") or evt.get("delta", "")
                if audio_b64:
                    # Base64 디코딩 후 PCM16 오디오 재생
                    pass
            elif t == "response.done":
                print()
                resp = evt.get("response", evt)  # GA 구조가 다를 수 있음
                usage = resp.get("usage")
                if usage:
                    print("이번 턴 사용량:", usage)
                break
            elif t == "error":
                print("오류:", evt)
                break

asyncio.run(main())

마이크 녹음, 스피커 재생, 이미지 입력, 턴별 및 누적 사용량 통계를 포함한 전체 상호작용 스크립트는 test_realtime.py를 참고하세요.

FAQ

연결 400: URL에 ?model=... 쿼리 파라미터가 포함되어 있는지 확인하세요.
연결 401: API Key가 유효하지 않거나 권한이 없습니다. GET /v1/models로 Key와 모델 가용성을 확인하세요.
전송 후 응답 없음: session.updated를 수신했고 response.create를 전송했는지 확인하세요.
500 후 연결 종료: 업스트림 오류로 WebSocket이 닫히므로 재연결이 필요합니다.
오디오 무음: 24 kHz PCM16 모노인지, Base64 증분을 올바르게 디코딩했는지 확인하세요.

더 많은 이벤트 유형과 필드는 OpenAI Realtime API 문서를 참고하세요.

API 문서

대화 및 텍스트

안전 및 오디오

이미지 시리즈

비디오 시리즈

텍스트 완성 및 임베딩

인터페이스 모듈

소개

인증

연결

세션 구성

메시지 전송

텍스트 입력

오디오 입력

응답 수신

사용량

필드 설명

Python 전체 예제

FAQ

​소개

​인증

​연결

​세션 구성

​메시지 전송

​텍스트 입력

​오디오 입력

​응답 수신

​사용량

​필드 설명

​Python 전체 예제

​FAQ

소개

인증

연결

세션 구성

메시지 전송

텍스트 입력

오디오 입력

응답 수신

사용량

필드 설명

Python 전체 예제

FAQ