OpenAI Realtime API क्लाइंट को WebSocket या WebRTC के ज़रिए जोड़ता है। सर्वर-साइड कनेक्शन के लिए, इंटरनेट वाली किसी भी मशीन से आप OpenAI तक सीधे पहुँच सकते हैं। क्लाइंट-साइड कनेक्शन के लिए — जो असल में आप इससे बनाना चाहेंगे उसका अधिकांश हिस्सा है — ब्राउज़र को एक सुरक्षित origin चाहिए और आपके backend को एफ़ेमेरल टोकन जारी करने होंगे। दोनों टनल के ज़रिए काम करते हैं। कुछ विवरण जानने योग्य हैं।
जुड़ने के दो तरीके, टनल करने के दो कारण
Realtime API सर्वर-साइड कनेक्शन (आपका backend OpenAI से WebSocket खोलता है) और क्लाइंट-साइड कनेक्शन (ब्राउज़र आपके backend द्वारा जारी एफ़ेमेरल टोकन से WebRTC peer कनेक्शन या WebSocket खोलता है) दोनों का समर्थन करता है। सर्वर-साइड रास्ते को टनल की ज़रूरत नहीं। क्लाइंट-साइड को लगभग हमेशा होती है।
क्लाइंट साइड को HTTPS क्यों चाहिए:
- ब्राउज़र की माइक्रोफ़ोन अनुमतियाँ एक सुरक्षित origin माँगती हैं।
- WebRTC का
getUserMediaऔर ICE हैंडलिंग HTTPS पर सबसे अच्छा काम करते हैं। - service worker (यदि कोई हों) को इसकी ज़रूरत है।
- यदि आप एफ़ेमेरल टोकन के लिए अपने backend के
/sessionएंडपॉइंट को कॉल करते हैं, तो आपका frontend HTTPS होने पर वह backend भी HTTPS होना चाहिए।
पहले को आप ब्राउज़र flags से टाल सकते हैं। मत करें। एक टनल इस्तेमाल करें और असली दुनिया में रहें।
विकास में एक Realtime ऐप का स्वरूप
एक न्यूनतम realtime ऐप के तीन हिस्से होते हैं:
- एक frontend जो माइक्रोफ़ोन इनपुट कैप्चर करता है और ऑडियो आउटपुट चलाता है।
- एक backend रूट जो आपके असली API key से OpenAI के
/v1/realtime/sessionsएंडपॉइंट को हिट कर एक एफ़ेमेरल टोकन जारी करता है। - एफ़ेमेरल टोकन का उपयोग करते हुए ब्राउज़र से OpenAI तक एक सीधा WebRTC या WebSocket कनेक्शन।
आपका टनल frontend + backend को एक्सपोज़ करता है (अधिकांश सेटअप में एक ही डोमेन)। असली realtime ट्रैफ़िक टनल से नहीं, ब्राउज़र-से-OpenAI जाता है — वह कनेक्शन HTTPS/WSS पर सीधा है।
PortPreview के साथ त्वरित सेटअप
- अपना dev server (Next.js, Vite, जो भी) पोर्ट 3000 या 5173 पर शुरू करें।
npx portpreview 3000चलाएँ।- ब्राउज़र में HTTPS URL खोलें। माइक्रोफ़ोन अनुमति के prompt सामान्य रूप से काम करते हैं।
- अपने टोकन-जारी एंडपॉइंट को हिट करें, एफ़ेमेरल टोकन प्राप्त करें, realtime कनेक्शन खोलें।
- बोलें, स्ट्रीम किया गया रिस्पॉन्स पाएँ।
यदि आप Vite इस्तेमाल कर रहे हैं, तो आपको Vite + टनल से allowedHosts और HMR config चाहिए होगा। यदि कहीं edge runtime वाले Next.js पर हैं, तो Node crypto चाहने वाली रूट्स पर runtime config का ध्यान रखें।
टनल के ज़रिए WebSocket upgrade
realtime कनेक्शन WebSocket हैं (या WebRTC, जो ज़्यादातर टनल को बायपास करता है)। आप जो भी टनल इस्तेमाल करें उसे HTTP Upgrade रिक्वेस्ट सही ढंग से फ़ॉरवर्ड करनी चाहिए। अधिकांश करते हैं — PortPreview, Cloudflare quick tunnels, ngrok सभी WebSocket upgrade संभालते हैं। यदि आपका नहीं करता, तो कनेक्शन ब्राउज़र में चुपचाप विफल होता है, एक सामान्य WebSocket closed before connected संदेश के साथ और बिना किसी उपयोगी विवरण के।
अनिश्चित हों तो wscat से upgrade टेस्ट करें। wss://your-tunnel.portpreview.dev/anything से जुड़ें और handshake देखें।
मदद करने वाली डेव तरकीबें
टोकन-जारी रिक्वेस्ट की जाँच करें
आपका frontend एक backend रूट को कॉल करता है जो OpenAI को कॉल करता है। यहाँ सबसे आम डेव बग /v1/realtime/sessions पर एक ग़लत कॉन्फ़िगर रिक्वेस्ट है — ग़लत मॉडल नाम, ग़लत voice, ग़लत modalities। आपका टनल frontend→backend रिक्वेस्ट कैप्चर करता है, पर backend→OpenAI hop नहीं। उस रिक्वेस्ट को सर्वर-साइड log करें, या दोनों परतों को लोकल पर चलाकर टनल के ज़रिए proxy करें।
ऑडियो फ़ॉर्मेट बेमेल
Realtime API डिफ़ॉल्ट रूप से कॉन्फ़िगर करने योग्य sample rate के साथ PCM16 इस्तेमाल करता है। यदि आप किसी अन्य फ़ॉर्मेट से ऑडियो डालते हैं, तो मॉडल या तो अस्वीकार करेगा या hallucinate करेगा। ब्राउज़र MediaRecorder आमतौर पर Opus या WebM देता है — आपको रूपांतरण संभालना होगा या वह WebRTC रास्ता इस्तेमाल करना होगा जो यह आपके लिए करता है।
लंबे सेशनों में टोकन समाप्ति
एफ़ेमेरल टोकन अल्पकालिक होते हैं। यदि आप टोकन के TTL से लंबा सेशन टेस्ट करते हैं, तो शेड्यूल के अनुसार रिफ़्रेश करें। Realtime SDK में इसके लिए helpers हैं; ख़ुद करने का मतलब है session.expired इवेंट पर नज़र रखना और पुराने के मरने से पहले नया टोकन जारी करना।
प्रोडक्शन में यह कैसा दिखता है
विकास से प्रोडक्शन तक एकमात्र असली बदलाव URL है: टनल hostname को अपने असली डोमेन से बदलें। टोकन-जारी एंडपॉइंट आपके backend पर रहता है। ब्राउज़र से OpenAI तक WebRTC/WebSocket कनेक्शन वही code path है। हमने टीमों को इसे ज़रूरत से ज़्यादा सोचते और realtime ट्रैफ़िक को अपने backend के ज़रिए proxy करने की कोशिश करते देखा है — मत करें, यह latency जोड़ता है और उस मॉडल को तोड़ता है जिसे OpenAI का SDK मानता है।
Anthropic की समानांतर पेशकश (जो स्ट्रीमिंग WebSocket से ज़्यादा एक tool use लूप के क़रीब है) के लिए, Anthropic tool use और webhook लोकल पर देखें। WebSocket upgrade को डिफ़ॉल्ट रूप से संभालने वाले टनल के लिए PortPreview की वेटलिस्ट में शामिल हों।