OpenAI Realtime API

OpenAI Realtime API란?

OpenAI Realtime API는 애플리케이션과 음성-음성 상호작용을 기본 지원하는 모델 간의 저지연 통신을 제공합니다. 오디오, 이미지, 텍스트 등의 멀티모달 입력과 오디오, 텍스트 등의 멀티모달 출력을 지원하여 대화형 음성 경험에 적합합니다.

음성 에이전트를 넘어 Realtime API는 WebSocket 연결을 통해 오디오를 스트리밍하여 실시간 오디오 전사를 사용할 수 있습니다. 문서에는 브라우저 기반 음성 에이전트 워크플로우를 위한 추천 시작 지점(예: TypeScript용 Agents SDK)이 강조되어 있습니다.

주요 기능

저지연 음성-음성 상호작용: 요청/응답 전용이 아닌 실시간 대화형 오디오 경험을 위해 설계되었습니다.
멀티모달 입력(오디오, 이미지, 텍스트): 애플리케이션 흐름에 따라 단일 세션에서 다양한 입력 유형을 수용할 수 있습니다.
멀티모달 출력(오디오 및 텍스트): 상호작용의 일부로 오디오, 텍스트 또는 둘 다를 반환할 수 있습니다.
다양한 연결 방식: WebRTC(브라우저/클라이언트 측), WebSocket(중간 계층 서버 측의 일관된 저지연), SIP(VoIP 전화) 중 선택하세요.
세션 및 대화 도구 가이드: 프롬프팅, 대화 수명 주기 이벤트, 서버에서 세션 동작 관리에 대한 지침을 포함합니다.
WebSocket을 통한 실시간 전사: 오디오 스트림을 실시간으로 전사하는 경로를 제공합니다.

OpenAI Realtime API 사용 방법

앱 실행 환경에 따라 연결 방식을 선택하세요: 브라우저/클라이언트는 WebRTC, 서버/중간 계층은 WebSocket, VoIP 전화는 SIP.
세션으로 시작하세요. 브라우저 음성 에이전트의 경우 문서에서 TypeScript용 Agents SDK를 권장하며, 이는 브라우저에서 WebRTC와 서버에서 WebSocket을 사용합니다.
코드에서 세션을 생성 및 초기화한 후 클라이언트 API 키를 사용하여 연결하세요(예시에서는 RealtimeAgent와 RealtimeSession에 session.connect 사용).
이벤트로 모델과 상호작용하세요. 연결 후 프롬프팅/조종, 대화 수명 주기 관리, 필요 시 웹훅을 통한 서버 측 제어 가이드를 사용하세요.

문서에는 Realtime 요청 인증에 영향을 미치는 GA 마이그레이션 세부 사항(FAQ 참조)이 명시되어 있습니다.

사용 사례

음성-음성 브라우저 기반 음성 에이전트: WebRTC(주로 TypeScript용 Agents SDK 사용)를 통해 마이크와 오디오 출력을 연결하여 대화형 대화를 구현하세요.
서버 기반 실시간 어시스턴트: 일관된 저지연 네트워킹과 중앙 집중식 세션 처리를 원할 때 중간 계층에서 WebSocket 연결을 사용하세요.
VoIP/전화 통합: 웹 브라우저가 아닌 전화 환경 배포 시 SIP를 통해 연결하세요.
실시간 오디오 전사: WebSocket을 통해 오디오를 Realtime 전사 흐름으로 스트리밍하여 오디오 전송 중 전사 결과를 받으세요.
멀티모달 상호작용: 단일 실시간 세션에서 오디오와 함께 이미지 및 텍스트를 수용한 후 오디오, 텍스트 또는 둘 다를 반환하세요.

자주 묻는 질문

GA Realtime API 사용 시 베타 헤더가 필요하나요?

GA 요청의 경우 문서에서 OpenAI-Beta: realtime=v1 헤더를 제거하라고 명시합니다. 베타 동작을 유지하려면 해당 헤더를 지속하여 포함하세요.

클라이언트 측(브라우저) Realtime 세션 자격 증명을 어떻게 생성하나요?

GA 인터페이스에서 문서는 단일 REST 엔드포인트—POST /v1/realtime/client_secrets—를 설명하며, 이는 클라이언트에서 WebRTC 또는 WebSocket 연결 초기화에 사용할 키를 생성합니다. 예시에서는 세션 구성을 생성하여 해당 엔드포인트에 게시합니다.

WebRTC와 WebSocket은 실행 위치에서 어떻게 다르나요?

문서에서 WebRTC는 브라우저/클라이언트 측 상호작용에 이상적이며, WebSocket은 일관된 저지연 네트워크 연결을 가진 중간 계층 서버 측 애플리케이션에 이상적이라고 설명합니다.

WebRTC SDP 검색에 적용되는 URL 변경은 무엇인가요?

브라우저에서 WebRTC 세션을 초기화할 때 문서에서 SDP를 통해 원격 세션 정보를 가져오는 URL이 이제 /v1/realtime/calls라고 명시합니다.

전체 음성 에이전트 동작 없이 Realtime API를 전사에 사용할 수 있나요?

네. 문서는 WebSocket 연결을 통해 오디오 스트림을 실시간으로 전사하는 실시간 오디오 전사를 구체적으로 언급합니다.

대안

Realtime 기본 요소 위에 직접 구축하지 않고 TypeScript용 Agents SDK 사용: 음성 에이전트 오케스트레이션에 집중하면서 브라우저(WebRTC)와 서버(WebSocket) 연결을 위해 내부적으로 Realtime을 활용할 수 있습니다.
스트리밍 대신 요청/응답 전사 파이프라인 구축: 앱에서 실시간 오디오 처리가 필요하지 않다면, Realtime에 설명된 이벤트 기반 세션 방식을 피할 수 있는 비실시간 전사 워크플로를 사용하세요.
음성용 기타 실시간 통신 방식: 전화 특정 흐름이 필요하다면 Realtime 연결 방법 내에서 SIP 기반 통합을 선택할 수 있습니다. 그렇지 않으면 배포에 따라 WebRTC(브라우저)와 WebSocket(서버) 중 선택하세요.
비실시간 엔드포인트와의 멀티모달 채팅: 지연 요구사항이 "저지연 통신"보다 덜 엄격하다면 비실시간 멀티모달 채팅 방식이 적합할 수 있지만, Realtime 문서에 설명된 동일한 스트리밍/이벤트 세션 워크플로를 따르지 않습니다.