Hướng dẫn sử dụng API để chuyển văn bản thành giọng nói SeaVoice
Truy cập tài khoản SeaVoice của bạn (bấm vào Avatar góc trái dưới trong Studio) để lấy x-api-key. API Key là khóa bí mật tĩnh, hãy copy và lưu trữ an toàn, chỉ gọi từ Server-side!
Dùng API để lấy danh sách các giọng nói có sẵn trong hệ thống qua endpoint GET /v1/tts/voices:
curl -X GET "https://api.seavoice.seateklab.vn/v1/tts/voices"Response trả về danh sách voices:
[
{
"voice_id": "Dp8TcVudawfON6pdX4YwOO",
"name": "Khánh Hà (Nữ miền Bắc)",
"description": "Giọng đọc nữ thanh thoát, chuẩn Hà Nội",
"language": "vi",
"gender": "female"
},
{
"voice_id": "rxvsDJWpCHdGYhQJjYES4H",
"name": "A Nam (Nam miền Nam)",
"description": "Giọng đọc nam truyền cảm, ấm áp miền Tây",
"language": "vi",
"gender": "male"
}
]Copy voice_id của giọng nói bạn muốn dùng (Ví dụ: Dp8TcVudawfON6pdX4YwOO).
Sử dụng endpoint POST /v1/tts/generate truyền kèm header x-api-key:
curl -X POST "https://api.seavoice.seateklab.vn/v1/tts/generate" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"text": "Xin chào, đây là giọng nói AI từ SeaVoice",
"voice_id": "Dp8TcVudawfON6pdX4YwOO",
"speed": 1.0,
"response_format": "audio"
}' \
--output "speech.wav"Chuyển văn bản thành giọng nói từ VoiceID chỉ định. Hỗ trợ biểu cảm tự nhiên ([laughter], [sigh], [whisper]), tự động phân đoạn thông minh cho văn bản dài, và cố định 16 diffusion steps để tối ưu tốc độ nhanh gấp đôi.
| Header | Bắt buộc | Mô tả |
|---|---|---|
| Content-Type | ✓ | application/json |
| x-api-key | ✓ | Khóa API bí mật của tài khoản để xác thực và trừ credit |
| Parameter | Type | Bắt buộc | Description |
|---|---|---|---|
| text | string | ✓ | Văn bản cần đọc (hỗ trợ chèn thẻ cảm xúc [laughter], [sigh]...) |
| voice_id | string | ✓ | Mã voice ID (lấy từ GET /v1/tts/voices) |
| speed | number | – | Tốc độ đọc (từ 0.5 đến 2.0, mặc định 1.0) |
| response_format | string | – | "audio" (trả về stream file WAV nhị phân) hoặc "base64" (trả về JSON chứa chuỗi Base64) |
| save_to_cloud | boolean | – | Mặc định là false khi gọi qua API để tiết kiệm dung lượng Cloud. Đặt true nếu muốn lưu lên Cloud. |
Khi response_format: "audio" (mặc định): Trả về trực tiếp nhị phân file âm thanh WAV (Content-Type: audio/wav).
Khi response_format: "base64": Trả về đối tượng JSON:
{
"audio_base64": "UklGRi4AAABXQVZFZm10IBAAAAABAAEA...",
"audio_url": "/outputs/out_20261012_114500_Dp8TcVu_9a1f.wav",
"sample_rate": 24000,
"format": "wav"
}curl -X POST "https://api.seavoice.seateklab.vn/v1/tts/generate" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"text": "Xin chào quý vị, đây là giọng đọc AI từ SeaVoice!",
"voice_id": "Dp8TcVudawfON6pdX4YwOO",
"speed": 1.0,
"response_format": "audio"
}' \
--output "speech.wav"Tự động phân tích nội dung văn bản để chọn chất giọng nói phù hợp nhất. Không cần truyền trước voice_id.
| Parameter | Type | Bắt buộc | Description |
|---|---|---|---|
| text | string | ✓ | Văn bản cần đọc |
| speed | number | – | Tốc độ đọc (mặc định 1.0) |
| response_format | string | – | "audio" (mặc định) hoặc "base64" |
curl -X POST "https://api.seavoice.seateklab.vn/v1/tts/auto-voice" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"text": "Chúc mừng bạn đã hoàn thành xuất sắc thử thách!",
"speed": 1.0,
"response_format": "audio"
}' \
--output "auto_voice.wav"Thiết kế giọng đọc mới hoàn toàn thông qua câu lệnh mô tả thuộc tính nhân vật (instruct), ví dụ: giọng nữ ấm áp, kể chuyện đêm khuya, hoặc giọng nam trầm phim tài liệu.
| Parameter | Type | Bắt buộc | Description |
|---|---|---|---|
| text | string | ✓ | Văn bản cần đọc |
| instruct | string | ✓ | Mô tả giọng (VD: "female, gentle, storytelling, calm soothing voice") |
| speed | number | – | Tốc độ đọc |
curl -X POST "https://api.seavoice.seateklab.vn/v1/tts/voice-design" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"text": "Đêm nay trăng sáng lung linh trên đỉnh núi.",
"instruct": "female, gentle, storytelling, calm soothing voice",
"speed": 1.0,
"response_format": "audio"
}' \
--output "voice_design.wav"Nhân bản giọng nói tức thì từ 5 đến 15 giây âm thanh mẫu (.wav, .mp3, .m4a).
curl -X POST "https://api.seavoice.seateklab.vn/v1/tts/voice-clone" \
-H "x-api-key: YOUR_API_KEY" \
-F "text=Xin chào, đây là giọng được nhân bản từ file mẫu của tôi." \
-F "ref_audio=@sample.wav" \
-F "speed=1.0" \
-F "response_format=audio" \
--output "cloned_speech.wav"Mô hình SeaVoice được cố định 16 diffusion steps tối ưu tốc độ cao. Một đoạn văn bản chuẩn (~200 ký tự) hoàn thành chỉ trong 1.5 – 3 giây.
Không bao giờ để lộ API Key trên frontend / mã nguồn phía trình duyệt client-side. Luôn thực hiện gọi API từ backend/server của bạn.
Mặc định khi gọi qua API, file âm thanh không lưu lên Cloud để tiết kiệm dung lượng. Chỉ thêm "save_to_cloud": true khi bạn cần lưu trữ lâu dài.
Quy định chuẩn: 1 ký tự = 1 credit. Hệ thống áp dụng cơ chế Two-Phase Debit an toàn: chỉ trừ credits khi âm thanh sinh thành công.
| Status Code | Trạng thái | Nguyên nhân & Cách xử lý |
|---|---|---|
| 200 OK | Thành công | Yêu cầu hợp lệ, trả về file âm thanh WAV hoặc chuỗi Base64. |
| 401 Unauthorized | Không có quyền | Thiếu header x-api-key hoặc API key không tồn tại / đã bị khóa. |
| 402 Payment Required | Số dư không đủ | Số dư credit trong ví của bạn không đủ để thực hiện sinh văn bản này. |
| 400 Bad Request | Dữ liệu sai | Thiếu trường bắt buộc (ví dụ thiếu text hoặc voice_id không hợp lệ). |
| 503 Unavailable | Hệ thống bận | Mô hình GPU đang khởi động. Vui lòng thử lại sau vài giây. |
Nếu bạn gặp khó khăn trong quá trình tích hợp API vào hệ thống hoặc cần cấp thêm hạn mức credit cho doanh nghiệp, vui lòng liên hệ đội ngũ kỹ thuật SeaVoice.