Tài liệu

Tài liệu API

Gọi dịch vụ của Vtube.vn (chuyển văn bản thành giọng nói) từ script, n8n hoặc phần mềm của bạn - không cần mở trình duyệt.

API là gì?

API cho phép phần mềm của bạn gọi trực tiếp tính năng TTS (text-to-speech) của Vtube.vn. Bạn xác thực bằng một API token (chuỗi bí mật dạng vt_…) thay cho việc đăng nhập. Mỗi lần gọi tốn credit y như khi dùng trên web.

Bước 1 - Đăng nhập & nạp credit

Gọi API tốn credit. Hãy đảm bảo tài khoản có đủ credit trước khi gọi.

Đăng nhập Nạp credit

Bước 2 - Tạo API token

Vào trang API → bấm Tạo token → copy ngay chuỗi vt_… hiện ra (chỉ hiện một lần duy nhất, không xem lại được).

Giữ token bí mật

Đừng chia sẻ hay commit token lên git. Nếu lỡ lộ, vào trang API thu hồi (revoke) và tạo token mới.

Bước 3 - Lấy danh sách giọng

Mỗi giọng đọc có một id. Gọi GET /v1/voices để lấy danh sách và chọn voiceSampleId bạn muốn dùng.

curl -X GET "http://localhost/api/v1/voices" \
  -H "Authorization: Bearer vt_xxxxxxxxxxxx"

Bước 4 - Gọi TTS

Gửi văn bản tới POST /v1/tts, nhận về file MP3. Thay vt_xxxxxxxxxxxx bằng token của bạn và abc123 bằng voiceSampleId ở bước 3.

curl -X POST "http://localhost/api/v1/tts" \
  -H "Authorization: Bearer vt_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Xin chào", "voiceSampleId": "abc123", "speed": 1.0}' \
  --output tts.mp3

Chi phí credit

TTS tính theo số ký tự văn bản, giống hệt khi dùng trên web. Mỗi lần gọi đều tạo audio mới và tính credit theo độ dài văn bản. Xem số dư & lịch sử ở trang Credit.

Lỗi thường gặp

401 - Token sai hoặc đã bị thu hồi. Tạo token mới.
402 - Không đủ credit. Nạp thêm ở trang Credit.
429 - Gọi quá nhiều trong thời gian ngắn. Chờ rồi thử lại.

Giới hạn

Văn bản tối đa 500.000 ký tự mỗi lần gọi (giống giới hạn trên web).
Tốc độ (speed) trong khoảng 0.5–2.0.
Token có thể đặt ngày hết hạn khi tạo.