Streaming API

Streaming API cho phép client gửi audio liên tục theo thời gian thực (realtime) qua WebSocket và nhận kết quả nhận dạng ngay lập tức (thời gian phản hồi trung bình ~ 500ms, tối đa 1s)

Tóm tắt luồng hoạt động

1. Kết nối WebSocket

2. Gửi cấu hình khởi tạo

3. Xác nhận từ hệ thống

4. Gửi dữ liệu âm thanh liên tục

5. Nhận kết quả theo thời gian thực

6. Thông báo khi hoàn tất gửi audio

7. Nhận kết quả cuối và kết thúc

Bước 1: Kết nối WebSocket

Client tạo kết nối WebSocket với API:

wss://api.vbee.vn/v1/stt/realtime?token=<token>&appId=<app-id>

Nếu token không hợp lệ → kết nối sẽ bị đóng ngay.

Nếu hợp lệ: Server xác thực token (tự động)

Bước 2: Gửi cấu hình khởi tạo (STREAMING_CONFIG)

Sau khi kết nối thành công, client bắt buộc gửi 1 message cấu hình bao gồm các tham số:

{
  "type": "STREAMING_CONFIG",
  "config": {
    "sampleRateHertz": 8000,
    "sampleSizeByte": 2,
    "channel": 1,
    "interimResults": true,
    "vadConfig": {
      "noInputTimeoutMs": 10000,
      "speechCompleteTimeoutMs": 800
    },
    "sessionId": "my-optional-session-id"
  }
}

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
sampleRateHertz	integer	Có	Tần số lấy mẫu (8000 hoặc 16000 Hz)
sampleSizeByte	integer	Có	Số byte mỗi sample (luôn = 2)
channel	integer	Có	Số kênh (chỉ hỗ trợ 1 – mono)
interimResults	boolean	Không	Nhận kết quả tạm thời khi đang nói Giá trị mặc định: false
sessionId	string	Không	Session ID tự đặt để tracking/debug
vadConfig.noInputTimeoutMs	integer	Không	Timeout (ms) nếu không phát hiện âm thanh. Range: 3000–10000
vadConfig.speechCompleteTimeoutMs	integer	Không	Thời gian im lặng (ms) để xác định hết câu. Range: 500–3000

Sau khi gửi config, cần chờ server trả về READY rồi mới gửi audio.

Bước 3: Xác nhận từ hệ thống (READY)

Server trả về sau khi sẵn sàng nhận audio:

{
  "type": "READY",
  "sessionId": "srv-session-abc123"
}

Bước 4: Gửi dữ liệu âm thanh liên tục (AUDIO_CHUNK)

Client gửi audio liên tục dưới dạng chunk:

{
  "type": "AUDIO_CHUNK",
  "audioContent": "<base64-encoded-raw-pcm>"
}

Yêu cầu audio:

Thuộc tính	Giá trị bắt buộc
Encoding	Raw PCM (Linear PCM, không có WAV header)
Bit depth	16-bit signed integer, little-endian
Channels	Mono (1 channel)
Sample rate	Phải khớp với sampleRateHertz trong STREAMING_CONFIG

Chunk size khuyến nghị:

Sample Rate	Chunk Size	Thời lượng
8000 Hz	1280 bytes	80ms — 1280 / (8000 × 2)
16000 Hz	3200 bytes	100ms — 3200 / (16000 × 2)

Gửi chunk đều đặn theo thời gian thực (80–100ms/chunk). Chunk không đều làm giảm chất lượng nhận dạng.

Bước 5: Nhận kết quả theo thời gian thực

5.1. Kết quả tạm thời (INTERIM_RESULT)

Kết quả trả về trong lúc người dùng đang nói, có thể thay đổi liên tục và không phải kết quả cuối cùng. Chỉ nhận được khi interimResults: true.

{
  "type": "INTERIM_RESULT",
  "text": "gần đó momo á",
  "isFinal": false,
  "stability": 0.8,
  "startTime": 11.36,
  "endTime": 12.96,
  "startVoiceTime": 11.68,
  "endVoiceTime": 12.64
}

Các kết quả nhận được như sau:

Tham số	Kiểu dữ liệu	Mô tả
text	string	Văn bản tạm thời, sẽ thay đổi ở interim tiếp theo
isFinal	boolean	Luôn là false
stability	float	Mức độ ổn định 0.0–1.0. Cao = ít thay đổi hơn
startTime	float	Thời điểm bắt đầu utterance (giây) trong stream
endTime	float	Thời điểm kết thúc tạm thời (giây) — tăng dần
startVoiceTime	float	Thời điểm phát hiện giọng nói bắt đầu
endVoiceTime	float	Thời điểm phát hiện giọng nói kết thúc tạm thời

5.2. Kết quả chính thức (FINAL_RESULT)

Kết quả trả về khi kết thúc một câu, là kết quả cuối cùng và không thay đổi.

{
  "type": "FINAL_RESULT",
  "text": "anh thanh toán momo á",
  "textRaw": " anh thanh toán momo á",
  "isFinal": true,
  "confidenceScore": 0.92,
  "startTime": 11.36,
  "endTime": 13.44,
  "startVoiceTime": 11.68,
  "endVoiceTime": 12.64,
  "speechType": "detected-speech",
  "status": "SUCCESS"
}

Các kết quả nhận được như sau:

Tham số	Kiểu dữ liệu	Mô tả
text	string	Văn bản chính thức, đã qua hậu xử lý
textRaw	string	Văn bản thô chưa xử lý
isFinal	boolean	Luôn là true
confidenceScore	float	Độ tin cậy 0.0 – 1.0
startTime	float	Thời điểm bắt đầu utterance (giây)
endTime	float	Thời điểm kết thúc tạm thời (giây)
speechType	string	detected-speech: có tiếng nói no-speech: không có tiếng nói
status	string	SUCCESS hoặc FAILURE

Bước 6: Thông báo khi hoàn tất gửi audio (DONE)

Gửi sau khi truyền hết toàn bộ audio

{
  "type": "DONE"
}

PING (Keep-alive) Gửi định kỳ mỗi 20–30 giây khi không có audio để duy trì kết nối.

{ "type": "PING" }

Server trả cho mỗi lần PING

{ "type": "PONG" }

Bước 7: Nhận kết quả cuối và kết thúc (STREAM_END)

Gửi sau khi server xử lý xong Done signal và đã gửi FinalResult cuối. Server sẽ đóng kết nối sau message này.

{
  "type": "STREAM_END",
  "sessionId": "srv-session-abc123",
  "totalUtterances": 4
}

Các kết quả nhận được như sau:

Tham số	Kiểu dữ liệu	Mô tả
sessionId	string	Session ID của session vừa kết thúc
totalUtterances	string	Tổng số utterance đã nhận dạng trong session

Khi session vượt quá 90 giây sẽ nhận được:

• type: ERROR

• code: SESSION_TIMEOUT

• message: Session exceeded maximum duration

Danh sách mã lỗi:

code	Giai đoạn	retryable	Mô tả
UNAUTHORIZED	AUTHENTICATING	false	Token không hợp lệ hoặc hết hạn
STT_INSUFFICIENT_SECONDS	AUTHENTICATING	false	Không đủ số giây trong tài khoản
STT_MAX_CCR_REACHED	AUTHENTICATING	true	Đã đạt giới hạn concurrent session
STT_INVALID_SAMPLE_RATE	CONFIGURING	false	sampleRateHertz không phải 8000 hoặc 16000
STT_INVALID_CHANNEL	CONFIGURING	false	channel không phải 1
STT_INVALID_SAMPLE_SIZE	CONFIGURING	false	sampleSizeByte không phải 2 (16-bit PCM)
PROVIDER_UNAVAILABLE	CONFIGURING / STREAMING	true	Provider không phản hồi hoặc lỗi tạm thời
PROVIDER_UNKNOWN	CONFIGURING / STREAMING	false	Provider trả về lỗi không xác định / không ánh xạ được
SESSION_TIMEOUT	STREAMING	false	Session vượt quá 90 giây
NO_INPUT_TIMEOUT	STREAMING	false	Không phát hiện âm thanh trong noInputTimeoutMs
RECOGNIZE_FAILED	Recognize	true	Recognize job thất bại ở provider (thường gặp ở async)
JOB_NOT_FOUND	Recognize	false	Không tìm thấy transcriptId khi poll /v1/stt/transcripts/:id
INTERNAL_ERROR	Bất kỳ	true	Lỗi nội bộ không xác định