실시간 음성

gpt-realtime으로 양방향 음성 에이전트를 구축하세요 — 모델이 음성을 듣고 실시간으로 음성으로 답합니다(전화 통화처럼). /v1/realtime에 대한 WebSocket 연결을 사용합니다. 기존 OpenAI Realtime SDK가 그대로 작동합니다. 엔드포인트를 저희 것으로 지정하고 Synthorai 키를 사용하기만 하면 됩니다.

엔드포인트 및 인증

모델을 쿼리 문자열에 넣어 /v1/realtime에 WebSocket을 엽니다. 인증은 업그레이드 전에 실행되므로 거부된 키는 소켓을 열지 못합니다.

# WebSocket, server-side (Node / Python / Go — anything that can set headers)
GET wss://synthorai.io/v1/realtime?model=gpt-realtime
Authorization: Bearer $YOUR_KEY
# Send only the Authorization header. Do NOT send OpenAI-Beta: realtime=v1
# (the beta protocol is retired; it makes the upstream reject the session).

• 당신의 sk-syn 키는 저희 게이트웨이를 벗어나지 않습니다 — 업스트림 자격 증명은 저희 쪽에서 교체됩니다.
• 서버 사이드 클라이언트를 위해 설계되었습니다(Node, Python, Go — Authorization 헤더를 설정할 수 있는 것이면 무엇이든). 브라우저 임시 토큰은 지원하지 않습니다.
• WebSocket만 지원합니다. SIP(전화)와 WebRTC는 클라이언트를 업스트림에 직접 연결하며 프록시되지 않습니다 — 전화 오디오는 WebSocket으로 브리지하세요.

세션 구성

연결이 열리면 session.created를 받습니다. session.update를 보내 보이스, 모달리티, 오디오 형식, 턴 감지를 설정하세요. GA 형식(session.type: "realtime", 오디오는 audio.input / audio.output 아래)을 사용하세요 — 예전의 평면 beta 형식은 폐기되었습니다.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "output_modalities": ["audio"],
    "instructions": "You are a concise customer-support agent.",
    "audio": {
      "input":  { "format": { "type": "audio/pcm", "rate": 24000 },
                  "turn_detection": { "type": "server_vad" } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    }
  }
}

최소한의 대화 턴:

1. input_audio_buffer.append로 마이크 오디오를 스트리밍합니다(base64 PCM).
2. input_audio_buffer.commit으로 턴을 커밋한 다음 response.create를 보냅니다.
3. 오디오 델타(response.output_audio.delta)와 텍스트 전사를 받은 다음, usage가 포함된 response.done을 받습니다.
4. server VAD를 활성화하면 모델이 턴을 자동으로 감지합니다. 수동 커밋 없이 동일한 이벤트가 흐릅니다.

도구, 함수 호출 및 지식

session.update에서 함수를 선언하세요. 모델이 대화 도중에 이를 호출합니다 — 이것이 주문 조회, 티켓 발행, 또는 모든 비즈니스 시스템을 연결하는 방법입니다. 결과를 반환하면 모델이 그것을 바탕으로 계속 말합니다:

// 1. Declare tools in session.update: "tools": [{ "type": "function", ... }]
// 2. The model emits a function_call in response.done.
// 3. Return the result, then ask the model to continue:
{ "type": "conversation.item.create",
  "item": { "type": "function_call_output",
            "call_id": "call_abc",
            "output": "{\"status\":\"shipped\"}" } }
{ "type": "response.create" }

원격 MCP 서버도 지원됩니다("type": "mcp") — 업스트림이 MCP 서버에 직접 연결합니다. 지식 베이스의 경우 instructions, RAG를 백엔드로 하는 함수 도구, 또는 MCP를 통해 사실을 주입하세요. 모델에 내장된 지식은 비즈니스 사실의 신뢰할 수 있는 출처가 아닙니다.

과금

response.done마다의 usage를 공식 정가로 과금합니다(마크업 없음) — 오디오와 텍스트, 입력과 출력, 그리고 캐시 입력 요율을 적용합니다. 각 세션은 종료 시 원장에 한 행을 기록합니다.

표시된 가격은 gpt-realtime / gpt-realtime-2.1 기준입니다. gpt-realtime-2.1-mini는 대략 3분의 1입니다. 오디오 입력은 ~10 tokens/second, 출력은 ~20 tokens/second입니다. 대화 기록을 추가 전용(append-only)으로 유지하면 캐시 요율($0.40/1M)이 긴 통화의 대부분을 흡수합니다.

세션 길이 및 핫 스위치

• 길어질 수 있는 통화의 경우 상한보다 충분히 이전(예: 50 minutes)에 핫 스위치하세요: 새 세션을 열고 conversation.item.create로 대화를 텍스트로 다시 재생합니다(사용자는 input_text, 어시스턴트는 output_text — 어시스턴트 오디오는 재생할 수 없습니다).
• 세션 재개는 없습니다: WebSocket이 끊기면 업스트림 상태가 손실됩니다. 재연결도 동일한 텍스트 재생 경로를 사용하므로 재연결 기능을 처음부터 구축하세요.
• 컨텍스트는 gpt-realtime-2.1 / -mini의 경우 128K(입력 오디오 기준 ≈3.5 hours)이며, 레거시 gpt-realtime은 32K입니다 — 긴 통화에는 사용하지 마세요.

액세스

gpt-realtime은 초대제 베타입니다. 카탈로그와 가격에는 표시되지만, 사용하려면 워크스페이스에 액세스 권한이 부여되어야 합니다 — 활성화하려면 저희에게 문의하세요.