Hướng dẫn LarVoice
Cách tạo audio, quản lý giọng nói, bảo vệ API key và dùng credits an toàn.
Bắt đầu
Đăng nhập vào LarVoice, mở trang Tạo audio, nhập nội dung, chọn giọng và bấm tạo. Khi audio hoàn thành, bạn có thể nghe thử hoặc tải về ngay trong lịch sử.
Nếu dùng LarVoice trong workflow cá nhân, hãy tạo API key trong trang Tích hợp và chỉ chia sẻ key này cho người chịu trách nhiệm kỹ thuật.
Giọng nói
Bạn có thể dùng giọng có sẵn trong thư viện hoặc tạo giọng cá nhân khi tài khoản đủ điều kiện. Với giọng cá nhân, chỉ tải lên bản ghi mà bạn có quyền sử dụng.
Đoạn ghi âm mẫu nên rõ tiếng, ít nhiễu, không có nhạc nền lớn và nằm trong giới hạn dung lượng hiển thị trên app.
API tạo audio
API chỉ dùng cho mục đích cá nhân, không thương mại. Base URL production là https://larvoice.com. Mọi request API v1 cần header Authorization: Bearer lv_your_api_key.
Luồng chuẩn gồm 2 bước: lấy danh sách giọng bằng GET /api/v1/voices, rồi tạo audio bằng POST /api/v1/tts. Response tạo audio trả luôn link file khi xử lý xong, không cần gọi lặp để chờ kết quả.
1. Lấy danh sách giọng
Gọi GET /api/v1/voices để lấy cả giọng public của LarVoice và giọng riêng mà tài khoản đã upload/clone. Copy cặp voice_id và voice_type sang request tạo audio.
curl --location 'https://larvoice.com/api/v1/voices?voice_type=all&language=vi&limit=20' \
--header 'Authorization: Bearer lv_your_api_key'Dùng voice_type=public để lấy giọng thư viện, voice_type=personal để lấy giọng cá nhân, hoặc voice_type=all để lấy cả hai. source vẫn được hỗ trợ như alias tương thích ngược.
curl --location 'https://larvoice.com/api/v1/voices?voice_type=public&language=vi&limit=20' \
--header 'Authorization: Bearer lv_your_api_key'curl --location 'https://larvoice.com/api/v1/voices?voice_type=personal&language=vi&limit=20' \
--header 'Authorization: Bearer lv_your_api_key'Query hỗ trợ: voice_type/source nhận all, public hoặc personal; q tìm theo tên, mã giọng và metadata; language lọc ngôn ngữ như vi, en, zh, ja, ko; gender, category, use_case dùng để lọc metadata giọng public. limit mặc định 50, tối đa 100.
{
"data": {
"voices": [
{
"source": "personal",
"voice_type": "personal",
"id": "7",
"voice_id": "7",
"name": "My Voice",
"language": "vi",
"preview_url": "https://larvoice.com/api/voices/audio?key=..."
},
{
"source": "public",
"voice_type": "public",
"id": "1",
"voice_id": "1",
"name": "Tuan",
"language": "vi",
"gender": "male",
"use_case": "tts",
"preview_url": "https://media.publit.io/file/larvoice/Tuan.mp3"
}
],
"next_cursor": 20,
"has_more": true
}
}Nếu response có has_more: true, gọi trang tiếp theo bằng cursor=next_cursor.
curl --location 'https://larvoice.com/api/v1/voices?voice_type=public&language=vi&limit=20&cursor=20' \
--header 'Authorization: Bearer lv_your_api_key'2. Tạo job TTS
Gọi POST /api/v1/tts với voice_id và voice_type đã lấy ở bước trên, kèm nội dung cần đọc trong gen_text. LarVoice trừ credits ngay khi nhận job. cost là số credits đã trừ cho request đó.
Giới hạn cố định cho API user là 60 request/phút trên mỗi API key và 2 tasks đồng thời cho mỗi user, áp dụng cho mọi plan. Nếu nhận 429, hãy giảm tốc độ gửi hoặc retry sau khi qua cửa sổ giới hạn.
curl --location 'https://larvoice.com/api/v1/tts' \
--header 'Authorization: Bearer lv_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"voice_id": "1",
"voice_type": "public",
"language": "vi",
"post_speed": 1,
"post_volume": 0,
"post_pitch": 1.0,
"return_srt": true,
"sentence_pause_ms": 350,
"line_break_pause_ms": 350,
"ellipsis_pause_ms": 350,
"split_by_sentence": true,
"gen_text": "Xin chào, đây là lar voice API."
}'Response 200 completed trả luôn output_url và aligned_srt_url khi upstream xử lý xong. job_id vẫn được lưu để xem lại lịch sử hoặc mở lại bằng job_url.
{
"data": {
"job_id": 123,
"status": "completed",
"cost": 36,
"output_url": "https://larvoice.com/api/tts/audio/tts-abc.zip",
"aligned_srt_url": "https://larvoice.com/api/tts/subtitles/tts-abc.srt",
"job_url": "https://larvoice.com/api/v1/jobs/123"
}
}Request fields
voice_id là số dương dạng chuỗi hoặc số. Dùng voice_type: "public" cho giọng thư viện và voice_type: "personal" cho giọng cá nhân; nhờ vậy hai loại giọng có thể trùng voice_id mà không ảnh hưởng nhau. gen_text là nội dung cần đọc, tối đa 50.000 ký tự mỗi request. normalize_text mặc định true để chuyển văn bản về chữ thường trước khi tạo audio; gửi false nếu cần giữ nguyên chữ hoa/thường. language mặc định vi. format nhận wav hoặc mp3, mặc định wav. return_srt mặc định true. Các field post_speed, post_volume, post_pitch, sentence_pause_ms, line_break_pause_ms, ellipsis_pause_ms là tùy chọn để chỉnh hậu kỳ và khoảng nghỉ. Nghỉ dấu phẩy do LarVoice cấu hình trong hệ thống. Gửi split_by_sentence: true để tách nội dung theo từng đoạn/câu do server xử lý và nhận file ZIP trong output_url.
3. Xem lại job đã lưu
Response tạo audio đã trả kết quả ngay. Nếu cần xem lại trạng thái/kết quả đã lưu, gọi GET /api/v1/jobs/:id bằng job_url. Không cần gửi lại nội dung tạo audio hoặc gọi lặp để chờ kết quả.
Các trạng thái chính: queued là đang chờ slot xử lý; processing là đang tạo audio; completed là audio đã sẵn sàng; failed là job lỗi và response có error.
Khi job completed, dùng output_url để stream hoặc tải file đầu ra. File có thể là MP3/WAV hoặc ZIP khi dùng split_by_sentence. Nếu có aligned_srt_url, bạn có thể tải subtitle SRT đã align theo audio.
{
"data": {
"job": {
"id": 123,
"status": "completed",
"output_url": "https://larvoice.com/api/tts/audio/tts/123.mp3",
"aligned_srt_url": "https://larvoice.com/api/tts/subtitles/tts/123.srt",
"output_expires_at": "2026-06-20 10:30:00"
}
}
}Tải file audio bằng URL trong output_url. URL này không cần Bearer token vì đã là link file output của job.
curl --location 'https://larvoice.com/api/tts/audio/tts/123.mp3' \
--output larvoice-output.mp3Nếu job failed, lưu error để debug hoặc hiển thị cho đội vận hành. Không nên retry vô hạn cùng một payload nếu lỗi là thiếu credits, sai voice_id hoặc nội dung không hợp lệ.
{
"data": {
"job": {
"id": 123,
"status": "failed",
"error": "Voice not found"
}
}
}Lỗi thường gặp
401 Unauthorized: thiếu API key, sai token hoặc key đã bị thu hồi. 402 Not enough credits: tài khoản không đủ credits. 404 Voice not found: voice_id không tồn tại hoặc giọng cá nhân không thuộc tài khoản API key. 429: gọi quá nhanh, vượt giới hạn 60 request/phút mỗi API key hoặc vượt 2 tasks đồng thời mỗi user. 400: payload thiếu field hoặc field không hợp lệ.
FAQ API
API dùng được cho mục đích thương mại không? Không. Tất cả API chỉ dùng cho mục đích cá nhân, không thương mại.
API có trả kết quả ngay không? Có. POST /api/v1/tts xử lý trong request và trả output_url khi audio hoàn tất.
Mỗi user chạy được bao nhiêu job cùng lúc? Tối đa 2 tasks đồng thời cho API TTS, áp dụng cho mọi plan.
Rate limit theo user hay API key? Rate limit là 60 request/phút cho mỗi API key.
Lưu ý tích hợp
Không gọi API trực tiếp từ frontend công khai nếu phải nhúng API key vào mã nguồn trình duyệt. Nên gọi LarVoice từ backend của bạn, hoặc tạo endpoint trung gian để bảo vệ key. File audio, link output và subtitle được lưu 7 ngày; hãy tải và lưu vào hệ thống của bạn nếu cần dùng lâu hơn.
Lịch sử và tải file
Lịch sử tạo audio, link audio và link subtitle được lưu 7 ngày. Hãy tải các file cần dùng trước khi hệ thống tự dọn.
Audio đã quá hạn sẽ không còn mở được từ lịch sử. Bạn có thể tạo lại từ nội dung cũ nếu vẫn còn credits.
Bảo mật
Không đăng API key lên website công khai, kho mã nguồn, nhóm chat hoặc tài liệu ai cũng xem được. Nếu nghi ngờ key đã bị lộ, hãy xóa key cũ và tạo key mới.
LarVoice có thể giới hạn hoặc tạm khóa thao tác bất thường để bảo vệ tài khoản, credits và chất lượng dịch vụ.
Hỗ trợ
Khi cần hỗ trợ, gửi mã audio, thời điểm phát sinh, mô tả vấn đề và email tài khoản tại trang Hỗ trợ. Đội LarVoice sẽ kiểm tra và phản hồi theo mức độ ảnh hưởng.