Realtime — Giọng nói thời gian thực

WSS wss://test.kailin.com.cn/v1/realtime

Hội thoại giọng nói song công thời gian thực dựa trên WebSocket (giao thức OpenAI Realtime) — được thiết kế cho trợ lý giọng nói, dịch trực tiếp và các kịch bản độ trễ thấp khác.

Kết nối

Tên mô hình được đặt trong query string; xác thực giống với các endpoint HTTP:

wss://test.kailin.com.cn/v1/realtime?model=gpt-4o-realtime-preview

const ws = new WebSocket(
  'wss://test.kailin.com.cn/v1/realtime?model=gpt-4o-realtime-preview',
  {
    headers: {
      Authorization: 'Bearer sk-your-token',
      'OpenAI-Beta': 'realtime=v1',
    },
  }
);

Ghi chú

new WebSocket của trình duyệt không thể đặt header tùy chỉnh. Hãy truyền token qua tham số subprotocol, hoặc proxy WebSocket qua backend riêng của bạn (khuyến nghị, giúp token không nằm ở frontend).

Định dạng tin nhắn

Tất cả tin nhắn đều là các text frame JSON có trường type.

Thiết lập phiên

Sau khi kết nối, máy chủ gửi session.created. Client thường gửi session.update trước để cấu hình giọng nói và phát hiện lượt nói:

{
  "type": "session.update",
  "session": {
    "instructions": "You are a voice assistant. Keep answers short.",
    "voice": "alloy",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_transcription": { "model": "whisper-1" },
    "turn_detection": { "type": "server_vad" }
  }
}

Gửi âm thanh của người dùng

Âm thanh được gửi theo từng chunk dưới dạng PCM16 mã hóa Base64 (24kHz mono):

{ "type": "input_audio_buffer.append", "audio": "<base64 pcm16>" }

{ "type": "input_audio_buffer.commit" }

Khi bật server_vad, máy chủ tự phát hiện điểm kết thúc lời nói và commit tự động — không cần commit thủ công.

Kích hoạt phản hồi

{
  "type": "response.create",
  "response": { "modalities": ["text", "audio"], "instructions": "Be enthusiastic." }
}

Sự kiện từ máy chủ

Sự kiện	Mô tả
session.created / session.updated	Phiên được tạo / cấu hình đã áp dụng
input_audio_buffer.speech_started / _stopped	VAD phát hiện bắt đầu / kết thúc lời nói
input_audio_buffer.committed	Bộ đệm âm thanh đã được commit
conversation.item.created	Mục hội thoại được tạo
response.audio_transcript.delta / _done	Delta / hoàn tất bản ghi lời đáp
response.audio.delta / _done	Delta âm thanh của lời đáp (Base64 PCM16)
response.text.delta / _done	Delta lời đáp dạng văn bản
response.done	Phản hồi hiện tại đã kết thúc
error	Sự kiện lỗi

Ví dụ luồng đầy đủ

const ws = new WebSocket(url);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: { voice: 'alloy', turn_detection: { type: 'server_vad' } },
  }));
  // send an audio chunk…
  ws.send(JSON.stringify({
    type: 'input_audio_buffer.append',
    audio: btoa(String.fromCharCode(...pcmChunk)),
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'response.audio.delta':
      playPcmChunk(atob(msg.delta));
      break;
    case 'response.audio_transcript.delta':
      appendSubtitle(msg.delta);
      break;
    case 'response.done':
      console.log('turn finished', msg.response.usage);
      break;
  }
};

Cảnh báo

Các endpoint Realtime tính phí theo thời lượng âm thanh và tốn kém hơn đáng kể so với văn bản. Hãy chú ý độ dài phiên khi thử nghiệm. Tính khả dụng phụ thuộc vào các mô hình được cấu hình trong kênh của bạn.