Realtime API

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

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

Method: POST

Tham số Header

Tham số	Giá trị	Kiểu dữ liệu	Tính bắt buộc	Mô tả
Authorization	Bearer {{token}}	String	Có	Token xác thực dạng Bearer: Bearer <access_token>
App-Id	{{app-id}}	String	Có	ID của ứng dụng người dùng tạo
Content Type	application/json	String	Có	Chỉ định kiểu nội dung gửi lên

Cấu trúc body của request

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
text	String	Bắt buộc	Văn bản đầu vào cần tổng hợp. Khoảng trắng đầu cuối sẽ được tự động loại bỏ (trim). Không được để trống. Tối đa 300 ký tự (≤ 300).
mode	String	Bắt buộc	Chế độ chuyển văn bản. *Giá trị bắt buộc là sync để sử dụng Realtime API
voiceCode	String	Bắt buộc	Mã giọng đọc dùng để chuyển đổi văn bản. Không được để trống. Lưu ý: Hiện chỉ hỗ trợ giọng Ngọc Huyền
outputFormat	String	Không	Định dạng loại tệp audio đầu ra *Giá trị mặc định: mp3 *Định dạng đầu ra. Hỗ trợ mp3, wav và pcm.
bitrate	Number	Không	Tốc độ bit của tệp audio (kbps) *Giá trị mặc định: 128 *Giá trị hợp lệ: 8, 16, 32, 64, 128
speed	Number	Không	Tốc độ đọc. *Giá trị mặc định: 1.0 *Giá trị từ 0.25 đến 1.9.
sampleRate	Number	Không	Tần số lấy mẫu (Hz) *Giá trị mặc định: giá trị cao nhất hỗ trợ cho giọng *Giá trị hợp lệ: 8000, 16000, 22050, 24000, 32000, 44100, 48000. Lưu ý: tùy vào từng giọng mà có các giá trị hỗ trợ riêng.

//REQUEST EXAMPLE: 

curl -X POST https://api.vbee.vn/v1/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "App-id: your-app-id" \
  -d '{
    "text": "Xin chào, đây là giọng nói tổng hợp từ Vbee.",
    "voiceCode": "hn_female_ngochuyen_full_48k-fhg",
    "outputFormat": "mp3",
    "bitrate": 128,
    "speed": 1.0,
    "mode": "sync"
  }' \
  --output output.mp3

//SUCCESS RESPONSE: trả về Audio binary data (MP3/WAV/PCM)

//FAILURE RESPONSE: 
//Khi có lỗi, response trả về dạng JSON:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "text must be less than or equal to 300 characters"
  }
}

Danh sách Error Codes

Code	HTTP status	Mô tả
UNAUTHORIZED	401	Token không hợp lệ, thiếu Authorization header, App-id
BAD_REQUEST	400	- Body request không hợp lệ (thiếu trường bắt buộc, text > 300 ký tự, outputFormat không hỗ trợ, ...) - Lỗi validation (ví dụ: voiceCode không tồn tại, sampleRate không hỗ trợ, syntax không hợp lệ) - Không đủ credit
TTS_CCR_MAX_LIMIT_REACHED	429	Vượt quá số lượng concurrent requests cho phép
TTS_SPEND_CREDITS_FAILED	500	Trừ credit thất bại
INTERNAL_SERVER_ERROR	500	Lỗi nội bộ