Tôi có thể kiểm thử OpenAI Realtime API trên localhost không?

Kết nối phía server không cần tunnel. Kết nối phía client từ trình duyệt cần HTTPS cho quyền micro và endpoint token tạm thời. Dùng tunnel để phơi bày dev server qua HTTPS, rồi kết nối trình duyệt trực tiếp tới OpenAI bằng token tạm thời.

Tunnel của tôi có cần hỗ trợ WebSocket cho Realtime API không?

Nếu bạn dùng transport WebSocket, có — tunnel phải chuyển tiếp các request nâng cấp HTTP. Đa số tunnel hiện đại làm được, nhưng nên kiểm tra bằng wscat trước khi truy đuổi một bug kết nối ma. WebRTC đi vòng qua tunnel cho chính lưu lượng realtime.

Vì sao kết nối realtime của trình duyệt cần token tạm thời?

Đặt API key đầy đủ vào trình duyệt là một thảm họa bảo mật. Backend của bạn phát hành một token tạm thời tồn tại ngắn, giới hạn cho một phiên realtime. Trình duyệt dùng token đó để kết nối trực tiếp tới OpenAI mà không bao giờ thấy API key thật của bạn.

Kiểm thử OpenAI Realtime API cục bộ qua tunnel

OpenAI Realtime API kết nối client qua WebSocket hoặc WebRTC. Với kết nối phía server, bạn có thể gọi OpenAI trực tiếp từ bất kỳ máy nào có internet. Với kết nối phía client — vốn là phần lớn những gì bạn thực sự muốn xây dựng — trình duyệt cần một origin an toàn và backend của bạn phải phát hành token tạm thời. Cả hai đều hoạt động qua tunnel. Có vài chi tiết cần biết.

Hai cách kết nối, hai lý do để tunnel

Realtime API hỗ trợ kết nối phía server (backend mở một WebSocket tới OpenAI) và kết nối phía client (trình duyệt mở một kết nối peer WebRTC hoặc WebSocket bằng một token tạm thời do backend phát hành). Đường phía server không cần tunnel. Phía client thì hầu như luôn cần.

Vì sao phía client cần HTTPS:

Quyền micro của trình duyệt đòi hỏi một origin an toàn.
getUserMedia và xử lý ICE của WebRTC chạy tốt nhất trên HTTPS.
Service worker (nếu có) cần nó.
Nếu bạn gọi endpoint /session của backend để lấy token tạm thời, backend đó cũng phải là HTTPS nếu frontend của bạn là HTTPS.

Điểm đầu tiên bạn có thể lách bằng cờ trình duyệt. Đừng. Hãy dùng một tunnel và sống trong thế giới thực.

Hình dáng của một app Realtime khi phát triển

Một app realtime tối thiểu có ba phần:

Một frontend bắt đầu vào micro và phát đầu ra âm thanh.
Một route backend phát hành token tạm thời bằng cách gọi endpoint /v1/realtime/sessions của OpenAI với API key thật của bạn.
Một kết nối WebRTC hoặc WebSocket trực tiếp từ trình duyệt tới OpenAI, dùng token tạm thời.

Tunnel của bạn phơi bày frontend + backend (cùng một domain trong đa số thiết lập). Lưu lượng realtime thực sự đi từ trình duyệt-tới-OpenAI, không qua tunnel của bạn — kết nối đó là trực tiếp qua HTTPS/WSS.

Thiết lập nhanh với PortPreview

Khởi chạy dev server (Next.js, Vite, gì cũng được) trên cổng 3000 hoặc 5173.
Chạy npx portpreview 3000.
Mở URL HTTPS trong trình duyệt. Lời nhắc quyền micro hoạt động bình thường.
Gọi endpoint phát hành token, lấy token tạm thời, mở kết nối realtime.
Nói, nhận phản hồi dạng stream.

Nếu dùng Vite, bạn sẽ cần config allowedHosts và HMR từ Vite + tunnel. Nếu dùng Next.js với edge runtime ở đâu đó, hãy để ý config runtime trên các route cần Node crypto.

Nâng cấp WebSocket qua tunnel

Kết nối realtime là WebSocket (hoặc WebRTC, vốn hầu như đi vòng qua tunnel). Bất kỳ tunnel nào bạn dùng đều phải chuyển tiếp đúng request HTTP Upgrade. Đa số làm được — PortPreview, Cloudflare quick tunnels, ngrok đều xử lý nâng cấp WebSocket. Nếu tunnel của bạn không làm, kết nối thất bại âm thầm trong trình duyệt với một thông báo chung chung WebSocket closed before connected mà không có chi tiết hữu ích.

Kiểm tra việc nâng cấp bằng wscat nếu bạn không chắc. Kết nối tới wss://your-tunnel.portpreview.dev/anything và quan sát handshake.

Những mẹo phát triển hữu ích

Kiểm tra request phát hành token

Frontend của bạn gọi một route backend, route này gọi OpenAI. Bug phát triển phổ biến nhất ở đây là một request cấu hình sai tới /v1/realtime/sessions — sai tên model, sai voice, sai modalities. Tunnel bắt request frontend→backend nhưng không bắt chặng backend→OpenAI. Hãy log request đó phía server, hoặc proxy qua tunnel bằng cách chạy cả hai lớp cục bộ.

Lệch định dạng âm thanh

Realtime API dùng PCM16 mặc định với sample rate cấu hình được. Nếu bạn đưa vào âm thanh ở định dạng khác, model sẽ từ chối hoặc ảo giác. MediaRecorder của trình duyệt thường cho bạn Opus hoặc WebM — bạn cần xử lý chuyển đổi hoặc dùng đường WebRTC vốn lo việc đó cho bạn.

Token hết hạn trong phiên dài

Token tạm thời tồn tại ngắn. Nếu bạn kiểm thử một phiên dài hơn TTL của token, hãy làm mới theo lịch. SDK Realtime có helper cho việc này; tự làm nghĩa là theo dõi sự kiện session.expired và phát hành token mới trước khi token cũ chết.

Trông như thế nào ở production

Thay đổi thực sự duy nhất từ phát triển sang production là URL: thay hostname tunnel bằng domain thật của bạn. Endpoint phát hành token vẫn ở backend. Kết nối WebRTC/WebSocket từ trình duyệt tới OpenAI là cùng một đường code. Chúng tôi từng thấy các nhóm nghĩ quá phức tạp và cố proxy lưu lượng realtime qua backend — đừng, nó thêm độ trễ và phá vỡ mô hình mà SDK của OpenAI giả định.

Về sản phẩm song song của Anthropic (gần với một vòng lặp tool use hơn là WebSocket dạng stream), xem Anthropic tool use và webhook cục bộ. Tham gia danh sách chờ PortPreview để có một tunnel xử lý nâng cấp WebSocket theo mặc định.