API đọc văn bản tiếng Việt

API chuyển văn bản tiếng Việt thành giọng nói, trả audio ngay trong lúc sinh. Dùng được theo ba cách:

• HTTP, tương thích API audio/speech của OpenAI;
• WebSocket, cho độ trễ thấp nhất và mốc theo câu;
• SDK Python và JavaScript, cùng plugin LiveKit và Pipecat.

Tài liệu này dành cho người tích hợp. Phần vận hành server xem README.md và DEPLOY.md.

Trong các ví dụ, $BASE là địa chỉ server (ví dụ https://tts.example.com) và $KEY là API key.

Bắt đầu nhanh

curl $BASE/v1/audio/speech -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"input": "Xin chào, tôi là trợ lý ảo."}' -o chao.mp3

from mon_ai import Client            # pip install ./clients/python
client = Client(api_key=KEY, base_url=BASE)
open("chao.mp3", "wb").write(client.speech("Xin chào!"))

import { Client } from "@mon-ai/sdk";    // clients/js
const client = new Client({ apiKey: KEY, baseUrl: BASE });
const mp3 = await client.speech("Xin chào!");

Thư viện openai cũng gọi được, chỉ cần đổi base_url:

from openai import OpenAI
client = OpenAI(api_key=KEY, base_url=f"{BASE}/v1")
client.audio.speech.create(model="tts-1", voice="alloy", input="Xin chào!").write_to_file("chao.mp3")

Xác thực và giới hạn

• Key: gửi Authorization: Bearer <key> trong mọi request. Riêng WebSocket còn nhận ?api_key=<key>, vì trình duyệt không đặt được header. Key nằm trong trang web thì người dùng trang đó đều xem được: hãy gọi API từ server của bạn, hoặc dùng một key riêng có hạn mức thấp.
• Hạn mức ký tự mỗi tháng:
  • Mỗi văn bản bị trừ số ký tự ngay khi bắt đầu đọc.
  • Văn bản bị huỷ trước khi có audio, hoặc hỏng do lỗi phía server, được hoàn lại.
  • Hết hạn mức thì nhận 429, mã insufficient_quota.
  • Tháng tính theo giờ Việt Nam. Xem số đã dùng ở GET /v1/usage.
• Số request chạy cùng lúc của mỗi tài khoản, tính cả request đang chờ: vượt thì nhận 429, mã concurrency_limit.
• Server đầy (mọi engine bận và hàng đợi đã đủ): nhận 429; thử lại sau ít giây.
• Văn bản: tối đa 5000 ký tự mỗi request.

Đọc văn bản qua HTTP: POST /v1/audio/speech

Body JSON giống OpenAI, thêm sample_rate:

Audio được gửi dần ngay khi sinh (chunked):

• byte đầu tiên đến sau khoảng 40 ms với pcm, wav, mulaw, và khoảng 65 ms với mp3 (đo trên server, chưa tính đường mạng);
• model sinh nhanh hơn thời gian thực khoảng 8 lần.

Header trả về:

• Content-Type: với pcm và mulaw có kèm tần số mẫu, ví dụ audio/pcm;rate=24000;
• X-Sample-Rate.

File wav khi stream có header ghi độ dài "không xác định". Đa số trình phát vẫn đọc được; SDK tự sửa header khi tải trọn file.

Văn bản được chuẩn hoá trước khi đọc. Không cần tự viết số, ngày, giờ, tiền, số điện thoại, đơn vị, từ tiếng Anh hay công thức ra chữ: 25-30°C, 2.500.000đ, 14h30, H2SO4, Vinhomes Grand Park đều được đọc đúng.

Độ trễ thấp nhất và mốc theo câu: WebSocket /v1/audio/stream

Mở wss://…/v1/audio/stream với header Authorization: Bearer <key>, hoặc với ?api_key=<key>. Sau đó gửi một văn bản dưới dạng JSON (text frame):

{"text": "Chào mừng quý vị. Chúc một ngày tốt lành!", "format": "pcm", "sample_rate": 24000, "speed": 1.0}

format là pcm (mặc định) hoặc mulaw; các trường khác giống HTTP. Server gửi lại các message sau:

• Một văn bản một lúc: chờ done rồi mới gửi văn bản tiếp, nếu không sẽ nhận lỗi busy. Nên giữ kết nối để đọc nhiều văn bản liên tiếp, đỡ mất thời gian mở lại.
• Huỷ: {"type": "cancel"} dừng văn bản đang đọc. Server dừng sinh ngay, rồi gửi done với "cancelled": true.
• Mốc theo câu: các câu được ghép thành đoạn tối đa khoảng 50 âm tiết, mỗi đoạn sinh một lần. start tính từ số mẫu âm thanh đã sinh nên khớp với audio nhận được, kể cả khi đổi speed. Muốn phụ đề từng câu thì gửi từng câu một; voice agent vốn làm như vậy.
• Ứng dụng:
  • phụ đề, hoặc tô sáng câu đang đọc (đoạn đang phát là đoạn cuối có start ≤ vị trí đang phát);
  • biết đã đọc tới đâu khi người dùng ngắt lời.
• Message có type mà client chưa biết thì bỏ qua: sau này có thể có thêm loại message mới.

Giọng đọc

• GET /v1/voices trả các giọng tài khoản dùng được: giọng có sẵn của dịch vụ, rồi giọng riêng của tài khoản.

  {"voices": ["ngoc-lan", "minh-khang", "v_k3j9…"], "default": "ngoc-lan",
   "details": [{"id": "ngoc-lan", "name": "Ngọc Lan", "gender": "female", "region": "north",
                "description": "Giọng nữ trẻ, rõ ràng"}],
   "custom": [{"id": "v_k3j9…", "name": "Giọng Lan", "seconds": 5.9, "denoised": false, "created": "…"}]}
  

  details mô tả các giọng có sẵn (gender: female, male hoặc rỗng; region: north, central, south hoặc rỗng). Danh sách và tên giọng có thể thay đổi; hãy đọc danh sách này thay vì ghi cứng id. Bỏ voice thì dùng giọng default.

• POST /v1/voices (multipart) tạo giọng riêng từ một bản ghi âm. Giọng dùng được ngay với "voice": "<id>".

  curl $BASE/v1/voices -H "Authorization: Bearer $KEY" -F file=@ghi_am.m4a -F name="Giọng Lan" -F consent=true
  # {"id": "v_k3j9…", "name": "Giọng Lan", "seconds": 5.9, "denoised": false, "created": "…"}
  

  • File: wav, mp3, m4a, ogg, webm…, tối đa 10 MB; server chỉ đọc 30 giây đầu.
  • Nội dung: 6–10 giây một người nói, ở phòng yên tĩnh. Cần ít nhất 2,5 giây giọng nói. Bản ghi ồn được khử nhiễu tự động.
  • consent=true là bắt buộc: bạn xác nhận người có giọng đã đồng ý cho tạo giọng.
  • Mỗi tài khoản có tối đa 20 giọng riêng (mặc định của server). Giọng riêng chỉ tài khoản tạo ra nó dùng được.

• DELETE /v1/voices/{id} xoá giọng riêng. GET /v1/voices/{id}/sample tải bản ghi đã làm sạch mà giọng được tạo từ đó (wav).

Lồng tiếng từ phụ đề: /v1/dubs

Đọc từng câu của file phụ đề tiếng Việt đúng thời điểm của nó, rồi trộn vào video hay âm thanh gốc. Việc chạy ở nền: gửi lên, rồi xem tiến độ và tải kết quả.

curl $BASE/v1/dubs -H "Authorization: Bearer $KEY" \
     -F subtitles=@tap1.srt -F media=@tap1.mp4 -F mode=voiceover -F name="Tập 1"
# {"id": "d_8f2k…", "status": "queued", "chars": 12840, ...}
curl $BASE/v1/dubs/d_8f2k… -H "Authorization: Bearer $KEY"          # status, done / total
curl "$BASE/v1/dubs/d_8f2k…/files/video?download=1" -H "Authorization: Bearer $KEY" -o tap1-long-tieng.mp4

Trường của POST /v1/dubs (multipart):

• Giới hạn mặc định của server: file tối đa 500 MB và 120 phút; mỗi tài khoản giữ tối đa 20 dự án. Dự án và file của nó tự xoá sau 7 ngày kể từ lần đổi cuối.
• Tính phí: mỗi câu tính số ký tự của nó, trừ vào hạn mức ngay khi gửi (hết hạn mức thì 429). Dự án đang chạy chiếm một request cùng lúc của tài khoản. Dự án lỗi được hoàn ký tự. Dự án bị huỷ chỉ tính các câu đã đọc.
• Thứ tự chạy: server làm lần lượt từng dự án. Mỗi câu chỉ dùng engine khi không có yêu cầu đọc trực tiếp nào đang chờ, nên lồng tiếng không làm chậm API realtime.

Các endpoint khác:

• GET /v1/dubs: danh sách dự án.
• GET /v1/dubs/{id}: chi tiết một dự án:
  • status: queued, running, done, failed hoặc cancelled;
  • stage, done, total: tiến độ theo câu;
  • lines: các câu;
  • placed: mỗi câu được đặt thế nào, gồm at (đọc từ giây thứ mấy), speed, duration, late (bắt đầu muộn bao nhiêu vì câu trước chưa xong), over (còn tràn bao nhiêu);
  • files: các file kết quả.
• GET /v1/dubs/{id}/files/{video|audio|voice|subtitles}, thêm ?download=1 để tải về:
  • video: video MP4 với âm thanh mới; hình được giữ nguyên, không nén lại; codec MP4 không chứa được thì xuất MKV;
  • audio: âm thanh đã trộn, M4A 48 kHz stereo;
  • voice: giọng đọc riêng, WAV 24 kHz;
  • subtitles: phụ đề SRT.
• POST /v1/dubs/{id}/render với JSON {"lines", "voice", "mode", "duck_db", "speed", "max_speed", "name"}, trường nào cũng không bắt buộc: xuất lại với lời đã sửa. Chỉ câu mới hoặc đã sửa được đọc lại và tính phí.
• POST /v1/dubs/{id}/cancel, DELETE /v1/dubs/{id}.
• GET /v1/dubs/{id}/lines/{i}: nghe một câu đã đọc (WAV).
• GET /v1/dubs/{id}/source: file gốc đã tải lên.
• POST /v1/dubs/parse: phụ đề thành {"lines"}, không lưu và không tính phí. Gửi file trong trường multipart subtitles, hoặc JSON {"text"}.

Nội dung lồng tiếng là do AI tạo. Khi đăng tải, khách hàng chịu trách nhiệm ghi nhãn theo Luật Trí tuệ nhân tạo, và phải có quyền với video gốc.

Lượng dùng: GET /v1/usage

?start=YYYY-MM-DD&end=YYYY-MM-DD; mặc định là tháng này.

{"customer": "acme",
 "quota": {"month": "2026-10", "monthly_chars": 1000000, "used_chars": 37408, "remaining_chars": 962592,
           "resets_at": "2026-11-01T00:00:00+07:00", "max_streams": 2, "running": 0},
 "period": {"start": "2026-10-01", "end": "2026-10-10"},
 "total": {"requests": 329, "chars": 37408, "audio_sec": 1807.3, "cancelled": 8, "errors": 0},
 "daily": [{"date": "2026-10-09", "requests": 281, "chars": 34645, "audio_sec": 1637.6, "cancelled": 4, "errors": 0}],
 "by_key": [...]}

GET /health không cần key: {"status": "ok", ...}, hoặc 503 khi server chưa sẵn sàng.

Lỗi

Mọi lỗi HTTP có dạng như của OpenAI: {"error": {"message": "...", "type": "...", "code": "..."}}.

Riêng WebSocket: key sai hoặc tài khoản bị khoá thì kết nối bị từ chối ngay khi mở (HTTP 403). Các lỗi khác đến dưới dạng message error.

SDK và tích hợp

Với voice agent, LLM trả lời theo kiểu stream. LiveKit và Pipecat tự gom chữ thành từng câu, rồi gửi mỗi câu là một request: câu đầu có tiếng sau khoảng 50 ms. Với tổng đài, dùng sample_rate 8000, hoặc mulaw qua WebSocket, để khỏi phải đổi tần số mẫu.