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
Kết nối WebSocket
Gửi cấu hình khởi tạo
Xác nhận từ hệ thống
Gửi dữ liệu âm thanh liên tục
Nhận kết quả theo thời gian thực
Thông báo khi hoàn tất gửi audio
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 (StreamingConfig)
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ố:
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": "abc123"
}
Bước 4: Gửi dữ liệu âm thanh liên tục (AudioChunk)
Client gửi audio liên tục dưới dạng chunk:
{
"type": "AudioChunk",
"audioContent": "<base64-audio>"
}
Yêu cầu audio:
Format: Raw PCM (không có WAV header)
16-bit, mono
Sample rate phải khớp với config
Khuyến nghị:
Gửi mỗi 80–100ms audio / lần
Gửi đều để đảm bảo 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 (InterimResult)
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.
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 (FinalResult)
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.
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"
}
Bước 7: Nhận kết quả cuối và kết thúc (StreamEnd)
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.
sessionId: Session ID của session vừa kết thúc
totalWords: 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
Last updated