LarVoice API Hub

Quản lý API Key

LarVoice API Documentation

Tài liệu tham khảo tổng hợp các REST API được sử dụng trong hệ thống LarVoice Studio (bao gồm Text-to-Speech và SRT-to-Audio).

Xác thực (Authentication)

Hầu hết các endpoints đều yêu cầu header xác thực chứa API_KEY hoặc Token.

Authorization: Bearer <YOUR_TOKEN>

Base URL

https://larvoice.com/api/v2

1. Core Endpoints

GET /me

Lấy thông tin tài khoản người dùng, bao gồm thông tin số dư (credits), gói cước (plan), và ngày hết hạn.

Response (200 OK)

{ "status": "success", "data": { "name": "Nguyên Lê", "email": "[email protected]", "credits": 500000, "planName": "PRO", "planDateStr": "Còn 15 ngày" } }
GET /voice?page={page}&per_page={limit}&group={region_id}&gender={0|1}&q={keyword}

Lấy danh sách các giọng đọc AI, có phân trang và hỗ trợ lọc theo ngôn ngữ, giới tính.

Response (200 OK)

{ "status": "success", "data": { "current_page": 1, "data": [ { "id": 1, "name": "Khải Ân", "gender": 1, "language_name": "Tiếng Việt" } ] } }
GET /languages

Lấy danh sách các vùng ngôn ngữ (Region/Language) để hiển thị trong bộ lọc giọng đọc ngang (Tabs).

{ "status": "success", "data": [ { "id": "vi", "name": "Tiếng Việt" } ] }

2. TTS Studio API

POST /tts_stream

Khởi tạo một tác vụ chuyển văn bản thành giọng nói (Text-To-Speech) dạng luồng. API này hỗ trợ phân vai giọng đọc trong một văn bản duy nhất.

Request Body (JSON - Editable)

{ "text": "Nội dung cần đọc...", "ref_voice_id": 1, "language": "vi", "audio_format": "mp3", "quality": "mini", "split_by_newline": false, "speed": 1.0, "run_speed": 1.0, "pitch": 1.0, "volume": 1.0, "strength": 2.2, "bass": 0, "treble": 0, "compress": 0, "first_trim_ms": 0, "last_trim_ms": 0 }

Response (200 OK)

{ "status": "success", "message": "Task created", "task_id": "8r4f8r-9fj4-kf9j", "chunks": [ ... ] }
GET /tts_stream/status/{task_id}

Long-polling hoặc gọi định kỳ để theo dõi trạng thái hoàn thành của từng câu (chunk) trong tác vụ TTS.

Response

{ "status": "success", "chunks": { "0": 1, // chunk 0 hoàn tất "1": 0 // chunk 1 đang xử lý }, "urls": { "0": "https://storage.larvoice.com/audio/0.mp3" }, "global_status": "processing" }
POST /tts_stream/edit_chunk

Sửa đổi một đoạn âm thanh cụ thể (Chunk) bằng cách cung cấp văn bản hoặc giọng mới.

Request Body (JSON - Editable)

{ "task_id": "8r4f8r-9fj4-kf9j", "chunk_index": 2, "text": "Câu nói mới cần chỉnh sửa", "voice_id": 5, "speed": 1.2 }

Response

...
GET POST DELETE
/profile/{id_or_type}

Lưu trữ và tải các profile chứa thông số cài đặt cá nhân (pitch, speed, volume, split layout) trên hệ thống đám mây.

...
GET POST DELETE
/pronunciation/{id?}

REST API quản lý từ điển cá nhân. Dùng để thay thế các từ viết tắt, tiếng lóng, tiếng anh trước khi tạo âm thanh.

Request Body (JSON - Editable)

{ "original_word": "ko", "modified_word": "không", "status": 1 }

Response

...

3. STA (SRT-To-Audio) API

POST /stt_stream

Khởi tạo tác vụ lồng tiếng và sinh Audio dựa trên định dạng phụ đề SRT. Trả về cấu trúc chunk được tính toán độ dài phát âm khớp với thời gian trên phụ đề.

Request Body (JSON - Editable)

{ "srt": "1\n00:00:00,000 --> 00:00:02,000\n[Nam] Xin chào!\n\n2\n00:00:02,000 --> 00:00:04,000\n[Nữ] Chào anh nha.", "ref_voice_id": 1, "language": "vi", "cast_map": { "Nam": {"voiceId": 2, "name": "Dũng"}, "Nữ": {"voiceId": 4, "name": "Lan"} }, "audio_format": "mp3", "quality": "mini", "speed": 1.0, "run_speed": 1.0, "pitch": 1.0, "volume": 1.0, "strength": 2.2, "bass": 0, "treble": 0, "compress": 0, "first_trim_ms": 0, "last_trim_ms": 0 }

Response

...
GET /stt_stream/status/{task_id}

Hoạt động tương tự endpoint của TTS Stream, giám sát trạng thái render audio cho từng timeline.

Response

...
POST /stt_stream/edit_chunk

Sửa đổi một đoạn lồng tiếng nhỏ. Nội dung được chỉnh sửa và render lại để khớp vào dòng thời gian (timeline interval).

Request Body (JSON - Editable)

{ "task_id": "8r4f8r-9fj4-kf9j", "chunk_index": 2, "text": "Câu nói mới cần chỉnh sửa", "voice_id": 5, "speed": 1.2 }

Response

...
POST /stt/transcribe Upcoming

Chuyển đổi âm thanh thu âm sẵn hoặc file thành văn bản và timestamps.

Request Body (JSON - Editable)

{ "audio_url": "https://example.com/audio-snippet.mp3", "language": "vi" }

Response

...

Error Handling

Khi có lỗi xảy ra, LarVoice sẽ trả về mã HTTP tiêu chuẩn kèm theo cấu trúc JSON giải thích nguyên nhân cụ thể.

  • 400 Bad Request: Tham số không hợp lệ (văn bản quá dài, sai voice_id).
  • 401 Unauthorized: API Key bị thiếu hoặc sai.
  • 403 Forbidden: API Key không đủ đặc quyền hoặc đã bị xóa.
  • 402 Payment Required: Bạn không đủ số dư tín dụng (credits) để tiếp tục request.
  • 429 Too Many Requests: Vượt quá giới hạn rate limit (Mặc định: 60/phút).
  • 500 Internal Server Error: Lỗi hệ thống hoặc Acoustic model sinh lỗi.

Ví dụ cấu trúc lỗi (JSON)

{ "success": false, "error_code": "INSUFFICIENT_CREDITS", "message": "Your account has run out of characters." }

Best Practices

  • Tham gia cơ chế caching (lưu bộ nhớ tạm) bên phía ứng dụng của bạn để tái sử dụng ngay kết quả audio đã render, tránh việc sinh lại văn bản trùng lặp.
  • Luôn fetch / kiểm tra /me lúc khởi động ứng dụng để phát hiện kịp thời tình trạng API Key bị vô hiệu hóa hoặc cạn kiệt Quota.
  • Khi nhúng (embed) vào hệ thống SaaS riêng, hãy đảm bảo Validation số luợng ký tự người dùng nhập vào sao cho không vượt qua giới hạn của LarVoice để tránh phản hồi 400 Bad Request.