OlokaTTS API Reference
Tài liệu đặc tả toàn diện cho lập trình viên. Tích hợp công nghệ tổng hợp giọng nói tiếng Việt chuẩn phòng thu 48kHz, nhân bản giọng đọc và kiểm soát cảm xúc vào ứng dụng của bạn.
Bạn muốn kết nối qua Model Context Protocol hoặc ChatGPT Actions?
Xem hướng dẫn MCP →Cơ Chế Xác Thực Bằng API Key
Mọi yêu cầu gọi đến OlokaTTS API phải được xác thực thông qua HTTP Header Authorization với định dạng Bearer Token.
• Bạn có thể tạo và quản lý nhiều API Key tại trang Cài Đặt > Developer API Keys.
• Khóa bí mật có tiền tố oloka_live_ và chỉ được hiển thị 1 lần duy nhất khi vừa tạo.
Tạo file âm thanh đồng bộ tương thích 100% chuẩn OpenAI TTS
| Thuộc tính | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
| input | string | Có | - | Nội dung văn bản tiếng Việt cần đọc. Hỗ trợ emotion tags như [cười], [thở dài], [0.5s]. |
| voice | string | Không | "Hải Đăng" | Tên giọng đọc (ví dụ: Hải Đăng, Mai Anh, Anh Khôi, Trúc Ly, Quang Sơn, Adam bựa). |
| speed | float | Không | 1.0 | Tốc độ phát âm thanh (từ 0.5x đến 2.0x). |
| model | string | Không | "olokatts-v3-turbo" | Tên mô hình neural (VieNeu v3 48kHz). |
from openai import OpenAI
# Khởi tạo OpenAI Client trỏ về OlokaTTS Base URL
client = OpenAI(
base_url="https://phucsd-vieneu-gateway.hf.space/v1",
api_key="oloka_live_your_api_key_here" # Điền API Key của bạn
)
# Gọi hàm tạo âm thanh tiếng Việt 48kHz
response = client.audio.speech.create(
model="olokatts-v3-turbo",
voice="Hải Đăng",
input="Chào bạn! [cười] Tôi là giọng đọc trí tuệ nhân tạo OlokaTTS 48kHz.",
speed=1.0
)
# Lưu trực tiếp ra file âm thanh WAV Studio
response.stream_to_file("output.wav")
print("Đã tạo file output.wav thành công!")
Tạo tác vụ hàng đợi bất đồng bộ (Dành cho văn bản dài, sách nói, podcast)
Endpoint này lập tức trả về mã job_id và phân phối việc xử lý song song trên hạ tầng GPU Kaggle Dual Tesla T4 (hoặc Local CPU). Ứng dụng của bạn có thể thăm dò (poll) trạng thái cho đến khi hoàn thành.
| Thuộc tính | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
| prompt | string | Có | - | Đoạn văn bản cần đọc (không giới hạn độ dài câu). |
| voice_id | string | Không | "Hải Đăng" | Tên giọng đọc preset. |
| voice_type | string | Không | "preset" | "preset" hoặc "clone" (nếu clone, truyền ref_sample_id). |
| temperature | float | Không | 0.7 | Độ biến thiên cảm xúc & prosody (0.1 đến 1.5). |
| silence_p | float | Không | 0.15 | Độ dài khoảng lặng giữa các câu. |
| force_local | boolean | Không | false | Bắt buộc xử lý trên Local CPU ONNX thay vì chờ GPU Kaggle. |
{
"id": "job_3891239732d7",
"prompt": "Trời Hà Nội mùa này đẹp lắm...",
"voice_type": "preset",
"voice_id": "Hải Đăng",
"status": "queued",
"sample_rate": 48000,
"audio_url": null,
"duration": null,
"created_at": "2026-10-07T10:15:30.123456"
}
Tra cứu trạng thái và nhận đường dẫn tải file âm thanh hoàn tất
Trường status sẽ lần lượt chuyển qua các giai đoạn:
queued →
booting_kaggle (nếu worker GPU đang khởi động) →
processing →
completed.
{
"id": "job_3891239732d7",
"status": "completed",
"audio_url": "https://phucsd-vieneu-gateway.hf.space/audio_files/tts_job_3891239732d7.wav",
"duration": 8.45,
"sample_rate": 48000,
"worker_id": "kaggle_t4_gpu0_f7a1",
"execution_time": 1.42
}
Lấy danh sách 25 giọng đọc tuyển chọn 3 miền Bắc – Trung – Nam
Hỗ trợ lọc theo tham số Query: ?region=Nam hoặc ?gender=Nữ.
[
{
"id": "vp_haidang",
"name": "Hải Đăng",
"gender": "Nam",
"region": "Nam",
"description": "Trẻ trung, hiện đại, phong cách tự nhiên (Mặc định)",
"is_editors_pick": true,
"preview_audio_url": "https://phucsd-vieneu-gateway.hf.space/static/previews/haidang.mp3"
},
{
"id": "vp_maianh",
"name": "Mai Anh",
"gender": "Nữ",
"region": "Bắc",
"description": "Dịu dàng, chuẩn phát thanh, phong cách tin tức",
"is_editors_pick": true
}
]
Tải lên mẫu giọng 3–8 giây để nhân bản giọng đọc tức thì (Instant Voice Cloning)
| Field Form | Kiểu | Mô tả |
|---|---|---|
| name | string | Tên gợi nhớ của mẫu giọng clone (ví dụ: "Giọng Sếp", "Kendy"). |
| file | binary file | File âm thanh .wav hoặc .mp3 độ dài từ 3 đến 8 giây. |
| ref_text | string (tùy chọn) | Văn bản tương ứng với câu nói trong file audio để tăng độ chuẩn xác. |
Diễn Xuất Biểu Cảm Tự Nhiên
OlokaTTS hỗ trợ chèn trực tiếp các nhãn cảm xúc vào văn bản đầu vào. Mô hình neural sẽ tự động điều chỉnh ngữ điệu, hơi thở và sinh ra âm thanh chân thực tương ứng.
Tạo tiếng cười nhẹ hoặc ngữ điệu tươi vui, phấn khởi.
Thở dài, thể hiện tâm trạng buồn bã, bất lực hoặc sâu lắng.
Hạ thấp âm lượng, giọng nói thì thầm bí mật hoặc hồi hộp.
Tạo khoảng lặng ngắt nghỉ kịch tính giữa các ý.
Bảng Mã Phản Hồi HTTP
| Mã HTTP | Ý nghĩa | Nguyên nhân & Khắc phục |
|---|---|---|
| 200 OK | Thành công | Yêu cầu được xử lý trọn vẹn. Trả về binary WAV hoặc JSON kết quả. |
| 400 Bad Request | Dữ liệu không hợp lệ | Thiếu tham số bắt buộc `input` hoặc chưa cấu hình Kaggle API Key. |
| 401 Unauthorized | Chưa xác thực | API Key bị thiếu hoặc không chính xác. Kiểm tra lại header Authorization. |
| 403 Forbidden | Bị từ chối quyền | API Key đã bị thu hồi hoặc không có quyền gọi endpoint này. |
| 504 Gateway Timeout | Quá thời gian chờ | Worker Kaggle GPU bận hoặc đang khởi động lại kernel. Nên chuyển sang Async Job `/v1/tts/jobs`. |