Batch API
API hỗ trợ chế độ xử lý bất đồng bộ cho các tệp văn bản dài hoặc tác vụ cần thời gian xử lý lớn.
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 JSON
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
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ỏ. Không được để trống.
Tối đa 100.000 ký tự
mode
String
Có
Chế độ chuyển văn bản.
*Giá trị bắt buộc là async để sử dụng Batch API.
webhookUrl
String
Có
Webhook để nhận kết quả của request
voiceCode
String
Có
Mã giọng đọc dùng để chuyển đổi văn bả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 và wav.
Lưu ý: hiện tại chỉ hỗ trợ mp3 và wav, nếu truyền pcm lên thì sẽ tổng hợp văn bản lỗi..
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ị mặc định riêng.
emphasisIntensity
Number
Không
Mức độ nhấn nhá.
*Giá trị số nguyên từ 0 đến 100, phải là bội số của 10.
*Chỉ áp dụng cho một số giọng có hỗ trợ tính năng nhấn nhá.
clientPause
Object
Không
Cấu hình thời gian ngắt nghỉ (xem bảng bên dưới).
Cấu trúc clientPause
Tham số
Kiểu dữ liệu
Tính bắt buộc
Mô tả
majorBreak
Number
Không
Thời gian ngắt nghỉ dấu chấm phẩy (giây).
*Giá trị mặc định: 0.3
*Giá trị từ 0.1 đến 10.
mediumBreak
Number
Không
Thời gian ngắt nghỉ dấu phẩy (giây).
*Giá trị mặc định: 0.25
*Giá trị từ 0.1 đến 10.
paragraphBreak
Number
Không
Thời gian ngắt nghỉ xuống dòng (giây).
*Giá trị mặc định: 0.6
*Giá trị từ 0 đến 10.
sentenceBreak
Number
Không
Thời gian ngắt nghỉ dấu chấm câu (giây).
*Giá trị mặc định: 0.45
*Giá trị từ 0.1 đến 10.
Chú ý:
Các audio link trả về chỉ có thời hạn trong vòng 3 phút, sau 3 phút audio link sẽ hết hạn và không thể sử dụng. Audio vẫn sẽ được lưu trữ trên hệ thống trong vòng 3 ngày kể từ thời điểm chuyển văn bản thành công. Muốn lấy link mới, bạn gọi api Get Request (bên dưới) để lấy lại audio link mới.
Kết quả trả về:
requestId: ID của request, dùng để tracking
status: Trạng thái của request
error_code: mã lỗi
error_message: Mô tả chi tiết lỗi
Danh sách Error Codes
Code
HTTP status
Mô tả
UNAUTHORIZED
401
Token không hợp lệ, thiếu Authorization header, hoặc thiếu appId (trong body hoặc header app-id)
BAD_REQUEST
400
- Body request không hợp lệ. Ví dụ: thiếu trường bắt buộc, sampleRate không hợp lệ
- Lỗi cấu hình request không hợp lệ (ví dụ: voiceCode không tồn tại)
INTERNAL_SERVER_ERROR
500
Lỗi nội bộ
Last updated