API documentation

Tài liệu tham khảo đầy đủ cho LarVoice REST API. Tích hợp text-to-speech tiếng Việt vào ứng dụng của bạn.

Xác thực

Tất cả request tới LarVoice API đều cần xác thực bằng Bearer token. Bạn có thể tạo và quản lý API key tại trang API settings.

Thêm header Authorization vào mỗi request với giá trị Bearer sk_live_your_api_key. Giữ bí mật API key của bạn và không bao giờ chia sẻ hoặc đưa vào client-side code.

Xác thực

curl https://larvoice.com/api/v1/voices \
  -H "Authorization: Bearer sk_live_your_api_key"

Text-to-speech

Chuyển văn bản tiếng Việt thành giọng nói tự nhiên. Hỗ trợ tùy chỉnh giọng, tốc độ, định dạng, nhạc nền và các thông số hậu xử lý.

POST /api/v1/tts

Parameters

Tham số	Kiểu	Mô tả
`text` REQUIRED	string	Văn bản cần đọc
`voice_id` REQUIRED	string	ID giọng nói
`speed`	number	Tốc độ đọc 0.5-2.0. Mặc định `1.0`
`format`	string	Định dạng output. Mặc định `mp3`
`background_music_id`	string	ID nhạc nền
`post_speed`	number	Tốc độ hậu xử lý
`post_volume`	number	Âm lượng hậu xử lý
`post_pitch`	number	Pitch hậu xử lý

Request

curl -X POST https://larvoice.com/api/v1/tts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Xin chào, tôi là LarVoice",
    "voice_id": "ha_noi_01",
    "speed": 1.0,
    "format": "mp3"
  }'

Response

{
  "id": "job_8f2k9x3m",
  "status": "completed",
  "audio_url": "https://cdn.larvoice.com/audio/job_8f2k9x3m.mp3",
  "duration": 12.4,
  "credits_used": 1
}

Giọng nói

Lấy danh sách tất cả giọng nói khả dụng. Bao gồm giọng hệ thống và giọng bạn đã clone.

GET /api/v1/voices

Response

{
  "voices": [
    {
      "id": "ha_noi_01",
      "name": "Hà Nội 01",
      "gender": "female",
      "region": "northern",
      "preview_url": "https://cdn.larvoice.com/previews/ha_noi_01.mp3"
    },
    {
      "id": "sai_gon_01",
      "name": "Sài Gòn 01",
      "gender": "male",
      "region": "southern",
      "preview_url": "https://cdn.larvoice.com/previews/sai_gon_01.mp3"
    }
  ]
}

Webhooks

Cấu hình webhook URL tại trang API settings để nhận thông báo khi job hoàn thành. LarVoice sẽ gửi POST request tới URL của bạn với payload chứa thông tin job.

Webhook request sẽ có header X-LarVoice-Signature để bạn xác thực nguồn gốc request. So sánh signature này với webhook secret trong API settings.

Payload

Webhook payload

{
  "event": "tts.completed",
  "job_id": "job_8f2k9x3m",
  "audio_url": "https://cdn.larvoice.com/audio/job_8f2k9x3m.mp3",
  "duration": 12.4,
  "credits_used": 1,
  "created_at": "2025-01-15T08:30:00Z"
}

Rate limits

Rate limit phụ thuộc vào gói bạn đang sử dụng. Khi vượt quá giới hạn, API sẽ trả về HTTP status 429 Too Many Requests.

Gói	Requests / phút	Requests / ngày
Starter	20	500
Creator	60	2,000
API	120	5,000

Response headers kèm theo thông tin rate limit hiện tại:

Rate limit response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312200
Retry-After: 30

Khi nhận được response 429, hãy đợi theo giá trị Retry-After (tính bằng giây) trước khi gửi request tiếp theo.