Tài liệu API — AI Tiện Ích

Bắt đầu

API LiveSub dịch văn bản bằng AI, dùng chung số dư token với tiện ích. Base URL:

Tạo tài khoản — bạn nhận token dùng thử và API key đầu tiên.
Vào Tài khoản để tạo thêm key hoặc mua token.
Gửi request kèm header Authorization: Bearer sk_live_…

Xác thực

Mọi request tới /v1/translate và /v1/balance cần header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Giữ key bí mật — đừng nhúng key vào mã chạy trên trình duyệt của người dùng cuối. Gọi API từ server của bạn. Key bị lộ thì thu hồi trong trang Tài khoản.

POST/v1/translate

Dịch một đoạn văn bản.

Trường	Kiểu	Mô tả
`text`	string	Bắt buộc. Tối đa 5.000 ký tự.
`to`	string	Bắt buộc. Mã ngôn ngữ đích: `vi`, `en`, `zh`, `ja`, `ko`, `th`, `id`, `fr`, `es`…
`from`	string	Tuỳ chọn. Mặc định `auto` (tự nhận diện).
`provider`	string	Tuỳ chọn. Mặc định `deepseek`. Xem /v1/models.

Phản hồi 200

{
  "translation": "Rất vui được gặp bạn",
  "provider": "deepseek",
  "ms": 640,
  "usage": { "charged": 16, "balance": 19984 }
}

POST/v1/translate-page BASE

Dịch nhiều đoạn văn bản của một trang web trong một lần gọi (dùng để dịch cả trang). Chỉ tài khoản đang có gói Base hoặc Plus. Trừ vào số token chung của gói Base hoặc Plus (cùng kho với phụ đề); hết thì trừ token lẻ.

Trường	Kiểu	Mô tả
`segments`	string[]	Bắt buộc. Tối đa 120 đoạn, tổng 6.000 ký tự. Kết quả trả về đúng thứ tự.
`to`	string	Bắt buộc. Ngôn ngữ đích.
`from`	string	Tuỳ chọn, mặc định `auto`.

{ "translations": ["Trang chủ", "Tin mới nhất"],
  "usage": { "charged": 15, "plan": { "tokensLeft": 3499985, … }, "balance": 0 } }

POST/v1/tts

Đọc văn bản thành giọng nói, trả về file audio/mpeg (mp3). Danh sách giọng: GET /v1/tts. Tính 1 token mỗi ký tự (giọng HD +2), bật direct cộng thêm 1 token mỗi ký tự.

Trường	Kiểu	Mô tả
`text`	string	Bắt buộc. Tối đa 3.000 ký tự.
`voice`	string	Bắt buộc. Mã giọng lấy từ `GET /v1/tts` (ví dụ `hoai-my`, `vs-nam-tram`).
`direct`	boolean	Tuỳ chọn. Bật đạo diễn AI: đọc số thành chữ, chia câu, chỉnh nhịp theo cảm xúc.
`style`	string	Tuỳ chọn. Phong cách đọc khi bật `direct`, ví dụ `kể chuyện`, `tin tức`.

Phản hồi gồm header X-Charged (token đã trừ) và X-Available (token còn lại).

GET/v1/balance

Số dư của tài khoản sở hữu key: token lẻ, gói Base hoặc Plus (token còn lại trong kỳ) và tổng có thể dùng.

{ "balance": 19984, "plan": { "name": "Base 1 tháng", "tokensLeft": 3499984, … }, "available": 2519968 }

GET/v1/models

Danh sách model dịch đang có. Không cần key.

Mã lỗi

HTTP	`error`	Ý nghĩa
400	`text_and_to_required`	Thiếu `text` hoặc `to`.
400	`unknown_provider`	Model không tồn tại.
401	`invalid_api_key`	Thiếu key, sai key hoặc key đã bị thu hồi.
402	`insufficient_balance`	Không đủ token. Phản hồi có `balance` và `needed`.
403	`plus_required`	`/v1/translate-page` cần gói Base hoặc Plus đang hoạt động.
413	`text_too_long`	Văn bản vượt 5.000 ký tự — hãy chia nhỏ.
429	`rate_limited`	Quá 120 request/phút cho một key. Chờ rồi thử lại.
502	`translation_failed`	Nhà cung cấp AI lỗi. Không bị trừ token. Có thể thử lại.

Giá & giới hạn

1 token = 1 ký tự của text gửi lên. Chỉ trừ khi dịch thành công.
Giới hạn: 120 request/phút/key, 5.000 ký tự/request.
Token mua một lần, không hết hạn. Xem bảng giá.

Ví dụ code

cURL

curl /v1/translate \
  -H "Authorization: Bearer $LIVESUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Nice to meet you","to":"vi"}'

JavaScript (Node 18+)

const res = await fetch('/v1/translate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.LIVESUB_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Nice to meet you', to: 'vi' })
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.translation);

Python

import os, requests

r = requests.post(
    "/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['LIVESUB_KEY']}"},
    json={"text": "Nice to meet you", "to": "vi"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["translation"])