REST API v1 • OpenAI Compatible • 48kHz Studio

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.

dns
Production API Base URL
https://phucsd-vieneu-gateway.hf.space
vpn_key Lấy API Key Của Bạn
lock 1. Xác Thực (Authentication)

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.

Authorization: Bearer oloka_live_9f8a3c4b1e2d0a8b7c6d5e4f3a2b1c0d

• 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.

POST /v1/audio/speech

Tạo file âm thanh đồng bộ tương thích 100% chuẩn OpenAI TTS

48kHz Audio Stream
Request Body (JSON)
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).
Code Mẫu Tích Hợp:
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!")
POST /v1/tts/jobs

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)

Async Job Queue

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.

Request Body (JSON)
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.
Response (200 OK)
{
  "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"
}
GET /v1/tts/jobs/{job_id}

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.

Response Khi Hoàn Tất (200 OK)
{
  "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
}
GET /v1/voices

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
  }
]
POST /v1/voices/clone

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)

Multipart Form
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.
theater_comedy 7. Thẻ Cảm Xúc (Emotion Tags)

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.

[cười]

Tạo tiếng cười nhẹ hoặc ngữ điệu tươi vui, phấn khởi.

"Thật tuyệt vời quá [cười], tôi không ngờ là làm được!"
[thở dài]

Thở dài, thể hiện tâm trạng buồn bã, bất lực hoặc sâu lắng.

"Đã cố hết sức rồi [thở dài], nhưng mọi chuyện vẫn thế."
[thì thầm]

Hạ thấp âm lượng, giọng nói thì thầm bí mật hoặc hồi hộp.

"Đừng nói cho ai biết nhé [thì thầm], bí mật đấy!"
[0.5s] hoặc [1.0s]

Tạo khoảng lặng ngắt nghỉ kịch tính giữa các ý.

"Và người chiến thắng chính là... [1.0s] Nguyễn Văn A!"
error 8. Mã Lỗi & Xử Lý Lỗi

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`.
check_circle Đã sao chép vào bộ nhớ tạm!