Tài liệu API

Bắt đầu

1. Đăng ký tài khoản, tạo API key ở bảng điều khiển.
2. Vào Cloudflare → Realtime → SFU, tạo một app, dán App ID + App Secret vào mục Cài đặt Cloudflare. Băng thông tính vào tài khoản của bạn, 1 TB đầu mỗi tháng miễn phí.
3. Gọi hai lệnh dưới đây từ backend, rồi nhúng SDK vào trang.

Xác thực

Mọi lệnh /api/v1/* cần header:

Authorization: Bearer mtv_live_xxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyy

Khoá chỉ hiện một lần lúc tạo — server lưu bản băm, không lưu bản gốc. Mất khoá thì thu hồi và tạo khoá mới.

Tạo một phòng. Phòng sống 12 giờ.

{
  "ten": "Họp tuần 39",
  "cheDo": "hop",          // hop | hoi_thao | chi_tieng
  "toiDa": 8,              // 2–30, chế độ hoi_thao tối đa 300
  "ghiAm": false           // cần gói Doanh nghiệp
}
→ { "ok": true, "phongId": "p_1a2b3c4d5", "hetHan": 1790000000000 }

Cấp vé cho một người. Mỗi người một vé riêng. Vé sống 10 phút — cấp ngay trước khi người đó vào phòng.

{ "ten": "Nguyễn Văn A", "vaiTro": "chu_phong" }   // chu_phong | thanh_vien | nguoi_xem
→ {
  "ok": true,
  "ve": "eyJ0ZW5h...",
  "nguoiId": "ng_9f8e7d",
  "duongVao": "https://.../goi?ve=eyJ0ZW5h..."
}

Dùng duongVao nếu muốn xong việc ngay, hoặc lấy ve để tự dựng giao diện bằng SDK. Chỉ chu_phong được bật ghi âm và kết thúc phòng.

Trả cấu hình phòng và danh sách người đang trong phòng ngay lúc gọi.

→ { "ok": true, "phong": {...}, "truc": { "soNguoi": 3, "nguoi": [{ "id", "ten", "mic", "cam" }] } }

Đóng phòng và đẩy mọi người ra. Không đảo lại được.

→ { "ok": true, "thang": "2026-09", "phut": 1284.5, "gb": 12.83, "soPhong": 41,
     "hanMucPhut": 20000, "hanMucGb": 150, "nguonCredential": "khach" }

phut là phút-người, đo tại máy chủ. gb do máy khách tự báo qua RTCStats nên chỉ để tham khảo — số tính tiền chính thức là hoá đơn Cloudflare của bạn.

SDK trình duyệt

<script src="https://<tên miền>/sdk.js"></script>
<script>
const cuoc = new MTVideo({
  ve,                       // vé lấy từ backend của bạn
  bitrateToiDa: 600000,     // van chi phí: 600 kbps ≈ 0,27 GB/giờ mỗi luồng
  capVeLai: async () => (await fetch('/api/ve-moi')).json().then(d => d.ve)
});

cuoc.on('luong-noi-bo', s  => video0.srcObject = s);
cuoc.on('nguoi-vao',    n  => themO(n));
cuoc.on('luong-den',  ({ nguoiId, stream }) => ganVideo(nguoiId, stream));
cuoc.on('nguoi-ra',   ({ nguoiId }) => boO(nguoiId));
cuoc.on('trang-thai', g  => capNhatMicCam(g));
cuoc.on('ket-thuc',   () => hienManKetThuc());
cuoc.on('loi',        e  => console.warn(e.ma, e.thongDiep));

await cuoc.vao();            // hỏi quyền mic/cam rồi vào phòng
cuoc.batTat('mic', false);   // tắt micro
cuoc.chat('xin chào');
await cuoc.roi();
</script>

SDK tự nối lại khi mạng đứt. Vé chỉ sống 10 phút nên muốn nối lại sau đó, phải truyền capVeLai để SDK xin vé mới từ backend của bạn.

Ghi âm và biên bản

const banGhiId = await cuoc.batGhi();   // chỉ chu_phong, gói Doanh nghiệp
await cuoc.dungGhi();

Tiếng của mọi người được trộn lại, cắt thành từng đoạn 5 phút rồi đẩy lên R2. Sau khi chốt, hệ thống bóc chữ tiếng Việt và dựng biên bản: nội dung chính, việc đã thống nhất, việc cần làm kèm người phụ trách và hạn, vấn đề còn treo. Xem ở bảng điều khiển sau khoảng 1–5 phút.

Mã lỗi

Chi phí băng thông

Cloudflare tính 0,05 USD mỗi GB gửi ra, miễn phí 1.000 GB đầu mỗi tháng. Chiều đẩy lên miễn phí. Ước tính với video 600 kbps:

Số trên là ước tính theo bitrate cấu hình; số thật phụ thuộc chất lượng mạng của từng người. Hạ bitrateToiDa hoặc dùng chế độ chi_tieng là cách giảm chi phí nhanh nhất.