Realtime API

API với chế độ sync phù hợp với các tệp audio ngắn, cho phép xử lý và trả kết quả ngay trong response mà không cần polling. Thời gian phản hồi trung bình ~ 500ms, tối đa 1s.

URL: https://api.vbee.vn/v1/stt

Method: POST

Tham số Header

Tham số	Giá trị	Tính bắt buộc	Mô tả
Authorization	Bearer {{token}}	Có	Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn
App-Id	{{app-id}}	Có
Content Type	multipart/form-data	Có

Cấu trúc body của request

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
audioContent	File	Có	Tệp WAV — xem bảng giới hạn bên dưới Sample rate được chấp nhận: 8000,16000,22050,32000,44100,48000
audioUrl	String	Không	URL HTTP(S) trỏ đến tệp WAV — cùng giới hạn
mode	String	Có	Sync mode: Phù hợp cho tệp audio ngắn (Realtime STT)
webhookUrl	String	Không	URL để server POST kết quả khi job sync hoàn tất.

Giới hạn tệp như sau:

	Giới hạn	Điều kiện lỗi
Thời lượng	Thời lượng audio < 10 giây	400 nếu duration ≥ 10s
Kích thước tệp	Kích thước tệp < 10 MB	400 nếu size ≥ 10MB

Kết quả trả về

• Response Type: text/json

• transcriptId: ID transcript, dùng để poll kết quả

• status: trạng thái của API

  • PENDING: đang chờ xử lý

  • PROCESSING: đang nhận dạng

  • COMPLETED: xong

  • FAILED: thất bại

• transcript: Văn bản nhận dạng ghép từ tất cả các utterances

• utterances: Danh sách từng đoạn nhận dạng gồm text, startTime, endTime (giây)

• audioDurationSeconds: Thời lượng WAV (giây, làm tròn lên) dùng để tính prepaid billing

// Example Request
curl -X POST https://<host>/v1/stt \
  -H "Authorization: Bearer <token>" \
  -H "App-ID: <app-id>" \
  -F "audioContent=@recording.wav" \
  -F "mode=sync"

// Example Response
{
  "transcriptId": "job-uuid-123",
  "status": "COMPLETED",
  "transcript": "xin chào thế giới",
  "utterances": [
    {
      "text": "xin chào thế giới",
      "startTime": 0,
      "endTime": 3.2
    }
  ],
  "audioDurationSeconds": 4
}