API Text-to-Speech
Hướng dẫn chi tiết endpoint POST /api/v1/tts: thông số kịch bản, bảng tham số cấu hình giọng đọc, ví dụ mã nguồn và công cụ thử nghiệm tương tác.
1. Thông tin Endpoint
Endpoint chính để chuyển đổi kịch bản văn bản thành tệp âm thanh giọng đọc AI chất lượng cao. Hỗ trợ xuất định dạng MP3 tiêu chuẩn hoặc WAV nguyên gốc 24kHz.
2. Bảng tham số đầu vào (Request Parameters)
Dữ liệu được gửi lên dưới dạng đối tượng JSON trong phần Body của yêu cầu HTTP:
| Tên tham số | Kiểu dữ liệu | Bắt buộc? | Mặc định | Mô tả & Khoảng giá trị |
|---|---|---|---|---|
| input_text | string | Bắt buộc | — | Đoạn văn bản cần đọc. Hỗ trợ tiếng Việt có dấu và các ngôn ngữ ngoại quốc. Tối đa 50.000 ký tự mỗi request. |
| speaker_id | string | Tùy chọn | vi_male_leduc_mb | Mã định danh giọng đọc. Xem danh sách giọng khả dụng tại API Danh sách giọng đọc. |
| speed | float | Tùy chọn | 1.0 | Tốc độ đọc. Giá trị từ 0.5 (chậm một nửa) đến 2.0 (nhanh gấp đôi). Bước tăng khuyến nghị là 0.05 hoặc 0.1. |
| pitch | float | Tùy chọn | 1.0 | Cao độ của giọng nói (độ trầm bổng). Giá trị từ 0.5 (rất trầm) đến 1.5 (rất cao). |
| volume | number | Tùy chọn | 100 | Mức âm lượng đầu ra theo tỷ lệ phần trăm. Giá trị từ 0 đến 100 (hoặc tối đa 150% để khuếch đại âm thanh). |
| audio_type | string | Tùy chọn | "mp3" | Định dạng tệp âm thanh đầu ra. Hỗ trợ "mp3" (nén dung lượng nhẹ, tối ưu web) và "wav" (âm thanh gốc chất lượng cao). |
3. Ví dụ gọi API Text-to-Speech
Chọn tab ngôn ngữ tương ứng để xem cú pháp triển khai tích hợp trực tiếp vào dự án của bạn:
curl -X POST "https://api.bvoiz.com/api/v1/tts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_text": "Chào mừng bạn đến với nền tảng Bvoiz AI Voice! Công nghệ giọng đọc truyền cảm số một Việt Nam.",
"speaker_id": "vi_female_thuytrang_mb",
"speed": 1.0,
"pitch": 1.0,
"volume": 100,
"audio_type": "mp3"
}'4. Cấu trúc dữ liệu phản hồi
Khi xử lý thành công, API trả về mã trạng thái HTTP 200 OK cùng đường link audio_url sẵn sàng để tải xuống hoặc đưa vào thẻ phát <audio>:
{
"status": 1,
"result": {
"request_id": "req_1790488219_b8c712fa",
"audio_url": "https://api.bvoiz.com/storage/audio/req_1790488219_b8c712fa.mp3",
"speaker_id": "vi_female_thuytrang_mb",
"speaker_name": "Thùy Trang (Nữ - Bắc)",
"provider": "edge",
"char_count": 99,
"duration_sec": 5.48,
"file_size": 87680,
"expires_at": "2026-10-28T12:00:00Z",
"created_at": "2026-09-28T12:00:00Z"
}
}| Trường dữ liệu | Kiểu | Ý nghĩa |
|---|---|---|
| request_id | string | Mã định danh duy nhất của tác vụ tạo âm thanh (dùng để tra cứu lịch sử). |
| audio_url | string | Đường dẫn công khai tải về tệp âm thanh (lưu trữ trên CDN tốc độ cao). |
| char_count | integer | Số lượng ký tự thực tế đã được xử lý và trừ vào số dư credits của tài khoản. |
| duration_sec | float | Thời lượng tổng phát của file âm thanh tính theo đơn vị giây. |
| expires_at | ISO 8601 | Thời điểm tệp âm thanh hết hạn lưu trữ trên máy chủ (mặc định sau 30 ngày). |
5. Quy tắc trừ Credits & Thời hạn lưu trữ
Mỗi ký tự trong input_text (bao gồm cả dấu cách và dấu câu) tương đương với 1 credit. Không phát sinh chi phí ngầm khi tinh chỉnh tốc độ hoặc cao độ.
Các tệp âm thanh được lưu trữ an toàn trên mạng lưới phân phối Cloudflare R2 trong vòng 30 ngày. Bạn nên tải và lưu trữ trên máy chủ riêng nếu cần sử dụng lâu dài.
6. Trình thử nghiệm tương tác (API Playground)
Bạn có thể thay đổi văn bản, giọng đọc, tốc độ và gửi request thử nghiệm trực tiếp ngay dưới đây để xem kết quả JSON trả về trong thời gian thực:
Trình thử nghiệm API tương tác (Interactive API Tester)
Nhấn Gửi Test Request để xem dữ liệu trả về theo thời gian thực.
speaker_id và phân loại theo giới tính, vùng miền.