VELTRIX DEVELOPER

Giọng đọc cho ứng dụng của bạn

Tích hợp TTS tiếng Việt qua REST API. Sử dụng giọng hệ thống hoặc giọng clone của tài khoản, theo dõi tác vụ và tải audio WAV.

Tạo API token

1. Tạo token

Chọn quyền và hạn dùng trong Cài đặt tài khoản.

2. Chọn giọng

Lấy danh sách giọng và kiểm tra quyền sử dụng của gói.

3. Tạo và tải audio

Gửi văn bản, theo dõi tác vụ và tải WAV khi hoàn tất.

API v1 · Xác thực Bearer token

Địa chỉ API của môi trường hiện tại: http://localhost:3001/api/developer/v1

Endpoint	Quyền	Chức năng
GET /voices?page=1	voices:read	Giọng hệ thống và giọng riêng, 10 kết quả/trang.
GET /limits	tts:read	Đơn giá Credit và giới hạn TTS hiện hành.
POST /tts/jobs	tts:write	Tạo audio; gửi text, voiceId và Idempotency-Key.
GET /tts/jobs/:id	tts:read	Theo dõi trạng thái tác vụ thuộc tài khoản.
GET /tts/jobs/:id/audio	tts:read	Tải WAV của tác vụ đã hoàn tất.

# Chạy ở máy chủ. TOKEN là biến môi trường chứa API token.
curl "http://localhost:3001/api/developer/v1/voices?page=1" \
  -H "Authorization: Bearer $TOKEN"

# Lấy voiceId từ systemVoices hoặc cloneVoices có canUse=true.
curl -X POST "http://localhost:3001/api/developer/v1/tts/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: don-hang-123-loi-doc-1" \
  -d '{"text":"Xin chào, đây là lời đọc của tôi.","voiceId":"VOICE_ID"}'

# Dùng data.jobId trả về, thăm dò mỗi 3–5 giây.
curl "http://localhost:3001/api/developer/v1/tts/jobs/JOB_ID" \
  -H "Authorization: Bearer $TOKEN"

# Khi status=COMPLETED, tải WAV bằng cùng token.
curl "http://localhost:3001/api/developer/v1/tts/jobs/JOB_ID/audio" \
  -H "Authorization: Bearer $TOKEN" -o loi-doc.wav

Phản hồi JSON có dạng {success, data} hoặc {success: false, error: {code, message}}. Tạo tác vụ trả HTTP 202; gửi lại cùng khóa với cùng văn bản và giọng trả tác vụ cũ, không trừ Credit lần nữa. Dùng khóa mới khi muốn tạo một bản audio mới.

Trạng thái: QUEUED → PROCESSING → COMPLETED hoặc FAILED/CANCELLED. Chỉ tải audio khi COMPLETED. Credit được tạm giữ khi nhận tác vụ, chốt khi thành công và giải phóng khi thất bại. Quyền gói và đơn giá được lưu theo từng tác vụ.

HTTP 401: token sai, hết hạn hoặc đã thu hồi. HTTP 403: thiếu quyền hoặc gói không cho phép. HTTP 402: không đủ Credit. HTTP 429: quá nhiều yêu cầu, chờ theo Retry-After. Các mã như API_SCOPE_REQUIRED, TTS_TEXT_LIMIT_EXCEEDED và PLAN_LIMIT_EXCEEDED giúp ứng dụng xử lý lỗi. Giới hạn và đơn giá lấy từ tài khoản đang dùng; không cố định trong mã tích hợp.

Luôn gọi API từ máy chủ của bạn. Không đặt token trong trình duyệt, URL, log hoặc kho mã công khai. Nếu lộ token, thu hồi trong Cài đặt và tạo token mới.