TokenLab

Âm thanh & thời gian thực

Realtime WebSocket

Kết nối với các phiên thoại realtime qua WebSocket

GET
/v1/realtime

Tổng quan

Sử dụng endpoint này cho các phiên thoại realtime. Một yêu cầu GET thông thường sẽ trả về metadata của endpoint và không cần API key. Một yêu cầu nâng cấp (upgrade) WebSocket với ?model={model} sẽ mở một phiên với model đã chọn.

Chỉ những model có chi tiết liệt kê thao tác realtime mới có thể mở phiên. Hãy đọc supported_operations trong GET /v1/models/{model} trước khi kết nối. Chi tiết model này cũng liệt kê các sự kiện và trường mà một phiên chấp nhận, chẳng hạn như session.update hoặc response.create.

Phạm vi hỗ trợ

GET /v1/realtime là một tập hợp con của WebSocket. TokenLab chuyển tiếp các sự kiện realtime của model đã chọn. Nó không cung cấp các REST helper của OpenAI Realtime: tạo phiên, client_secrets, Calls hoặc các API phiên beta cũ.

Hãy lưu giữ các API key dài hạn trên server của bạn. Endpoint này không cấp phát client secret ngắn hạn cho trình duyệt hoặc ứng dụng di động.

Các phiên realtime sử dụng tùy chọn phân phối của API key hoặc Workspace. Header X-TokenLab-Delivery-Policy hoặc query string không thể ghi đè tùy chọn này.

Kết nối

modelstringquerybắt buộc

ID của realtime model. Bắt buộc đối với yêu cầu nâng cấp WebSocket.

Authorizationstringheaderbắt buộc

Bearer sk-your-api-key, được gửi kèm với yêu cầu nâng cấp. x-api-key cũng được chấp nhận. Khóa trong query string không được chấp nhận.

Yêu cầu

import WebSocket from 'ws';

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', 'grok-voice-latest');

const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.TOKENLAB_API_KEY}` }
});

socket.on('open', () => console.log('Realtime connection open'));

socket.on('message', (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === 'error') {
    console.error('Realtime error', event.status, event.error.code);
    return;
  }
  console.log('realtime event', event.type);
});

socket.on('close', (code, reason) => console.log('closed', code, reason.toString()));

Tin nhắn

TokenLab chuyển tiếp các message WebSocket giữa client của bạn và model. Hãy sử dụng định dạng sự kiện của model đó, và đặt model vào query string, chứ không phải trong từng sự kiện. Một message có thể có dung lượng tối đa 32 MiB.

Lỗi

Trước khi socket được mở, thông tin xác thực không chỉ định API key hợp lệ sẽ bị từ chối bằng mã HTTP 401, 403, 429, hoặc 503 kèm theo nội dung lỗi JSON.

Sau khi socket được mở, một phiên bị từ chối sẽ gửi một message JSON rồi đóng socket:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.codeNguyên nhân
missing_modelQuery parameter model bị trống
unsupported_operationModel không được phát hành cho Realtime API
model_not_allowed, insufficient_balance, quota_exceededKey không thể sử dụng model này, hoặc số dư hay hạn mức của key không đủ để chi trả khoản dự lưu cho phiên. Xem Xử lý lỗi API

Dịch vụ sẽ đóng socket với mã 1008 đối với các trường hợp bị từ chối này. Các mã đóng khác: 1009 khi message quá lớn, 1013 khi có tình trạng tồn đọng message, và 1011 khi dịch vụ không thể định tuyến hoặc chuyển tiếp phiên. Hãy xử lý lỗi theo code, không theo message.

Thanh toán và đóng phiên

Các phiên được tính phí trừ vào số dư API key của bạn. TokenLab tạm giữ một khoản ước tính khi bắt đầu, sau đó quyết toán mức sử dụng thực tế khi kết thúc và hoàn trả phần chênh lệch. Các model được tính phí theo token hoặc theo thời gian phiên, tùy theo thông tin chi tiết của từng model.

Hãy đóng socket phía client khi phiên hoàn tất. Nếu dịch vụ đóng phiên trước, TokenLab sẽ gửi một mã đóng tới client của bạn khi có thể.

Ví dụ phản hồi

JSON bên dưới là phản hồi cho một yêu cầu HTTP GET thông thường. Đây không phải là một sự kiện của phiên.

Phản hồi

HTTP GET
{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

Các trường quan trọng

objectstring
realtime.endpoint (khi gọi HTTP GET).
websocket_urlstring
/v1/realtime?model={model} (khi gọi HTTP GET).
protocolstring
tokenlab_realtime_proxy (khi gọi HTTP GET).

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Tham số truy vấn

model?string

ID của model realtime. Bắt buộc đối với các yêu cầu nâng cấp WebSocket; tùy chọn cho các kiểm tra metadata HTTP thông thường.

Phản hồi

application/json

application/json

application/json

application/json

application/json