API v1 · REST + JSON · UTF-8

Tài liệu API HLS Manager

Cho website và ứng dụng ngoài tra mã nhúng theo tiêu đề bài, nhập video từ link trực tiếp, sửa thông tin, và nhận webhook khi video mã hoá xong. Mọi phản hồi là JSON tiếng Việt; URL trong dữ liệu là địa chỉ tuyệt đối dùng được ngay.

Gốc API/api/v1

Gọi thử trong 1 phút

  1. Vào trang quản lý › Cài đặt › Khoá API › Tạo khoá. Copy khoá ngay — nó chỉ hiện một lần.
  2. Gọi danh sách video đã xong (thay KHOA_API bằng khoá vừa tạo):

Thấy {"items": [...], "total": …} là khoá chạy. Thấy 401 thì xem mục Xác thực.

Xác thực

Mọi yêu cầu tới /api/v1 cần khoá API (trang quản lý dùng cookie riêng, không liên quan). Gửi khoá trong header:

Riêng yêu cầu GET chấp nhận thêm tham số ?key=KHOA_API — tiện để dán thử trên trình duyệt, nhưng khoá sẽ nằm trong nhật ký máy chủ và lịch sử trình duyệt. Yêu cầu ghi (POST/PATCH/DELETE) chỉ nhận header.

QuyềnĐược gọi
readMọi endpoint Đọc (kể cả POST /videos/lookup tra hàng loạt).
writeĐọc + Ghi (nhập URL, sửa, mã hoá lại, xoá) + Webhook. Khoá read gọi endpoint ghi → 403 insufficient_scope.

Cất khoá trong WordPress

Đặt khoá trong wp-config.php (ngoài thư mục giao diện, không vào cơ sở dữ liệu). Các ví dụ PHP dưới đây dùng 2 hằng này:

Ví dụ JavaScript dùng 2 hằng tương ứng:

Không đặt khoá vào JavaScript chạy trên trình duyệt người xem (API có bật CORS nên gọi được, nhưng ai mở trang cũng đọc được khoá). Ví dụ JavaScript trong trang này chạy ở máy chủ (Node 18+ có sẵn fetch).

Giới hạn lượt & mã lỗi

Mặc định 600 lượt/phút cho mỗi khoá, tính theo cửa sổ trượt 60 giây. Phản hồi thành công kèm header cho biết còn bao nhiêu lượt:

Vượt giới hạn → 429 rate_limited kèm header Retry-After (số giây cần chờ) và trường retry_after trong thân lỗi. Khi đồng bộ hàng loạt, dùng tra 200 tiêu đề/lần thay vì gọi từng bài.

Dạng lỗi

Mọi lỗi trả JSON cùng một dạng — error là câu tiếng Việt để hiện cho người dùng, code là mã để chương trình rẽ nhánh:

HTTPcodeKhi nào
400invalid_requestThiếu/sai kiểu dữ liệu (API v1 không dùng 422). Cụ thể hơn: invalid_status, invalid_since, invalid_folder, invalid_title, too_many_titles, invalid_external_id, invalid_url, invalid_events, invalid_secret, private_address, unresolvable_host, too_many_webhooks.
401missing_api_keyKhông gửi khoá (hoặc gửi ?key= cho yêu cầu không phải GET).
401invalid_api_keyKhoá sai hoặc đã bị thu hồi.
401api_key_disabledKhoá đang bị tắt ở trang quản lý.
403insufficient_scopeKhoá chỉ đọc gọi endpoint ghi/webhook.
404video_not_foundKhông có video (hoặc đã xoá). Tương tự webhook_not_found, folder_not_found, not_found (sai đường dẫn, không cần khoá); sai phương thức → 405 method_not_allowed.
409not_readyLấy mã nhúng khi video chưa done.
409external_id_existsexternal_id đã gắn video khác.
409busy · no_sourceMã hoá lại khi video đang xử lý / không còn tệp nguồn (máy chủ mặc định xoá nguồn sau khi mã hoá xong).
429rate_limitedVượt giới hạn lượt — chờ Retry-After giây.
500 · 507server_error · insufficient_storageLỗi máy chủ / đĩa đầy. Thử lại sau, báo quản trị nếu lặp lại.

Cấu trúc video

Mọi endpoint trả video theo cùng một cấu trúc. Thời gian là ISO 8601 giờ UTC (đuôi Z). hls_url, embed_url, embed_code, thumb_url là null khi video chưa done.

Trạng thái: downloading (đang tải từ URL) → queued → encoding → done; hoặc error, cancelled. Video đã xoá không còn xuất hiện.

Đọc quyền read

Tra cứu video, mã nhúng, thẻ, thư mục, thống kê. Chỉ đọc, gọi bao nhiêu lần cũng không đổi dữ liệu.

Ghi quyền write

Nhập video, sửa thông tin, mã hoá lại, xoá. Chỉ gửi trường cần đổi.

Webhook quyền write

Thay vì hỏi đi hỏi lại “xong chưa”, đăng ký 1 URL — máy chủ tự POST khi video done, error hoặc bị xoá. Cũng đăng ký được ở trang quản lý › Cài đặt › Webhook.

Dữ liệu gửi tới URL của bạn

  • X-Hls-Signature = sha256= + HMAC-SHA256 (hex) của nguyên thân yêu cầu với secret của webhook. Tính trên chuỗi byte nhận được — đừng json_decode rồi mã hoá lại.
  • Trả mã 2xx trong 10 giây là thành công (máy chủ không theo chuyển hướng — 3xx tính là thất bại). Không được thì máy chủ thử lại 3 lần: sau 10 giây, 60 giây, 10 phút (tổng 4 lần gửi). X-Hls-Delivery giữ nguyên qua các lần thử — dùng để bỏ qua bản trùng.
  • sent_at đổi mỗi lần gửi; từ chối yêu cầu có sent_at cũ hơn ~15 phút để chống phát lại.
  • video.done: mã hoá xong · video.error: lỗi mã hoá hoặc lỗi tải từ URL · video.deleted: xoá từ trang quản lý, API hoặc xoá hàng loạt. Huỷ việc (cancelled) không gửi.

Xác minh chữ ký

Quản lý webhook qua API

Tích hợp WordPress: gắn mã nhúng theo tiêu đề bài

Tình huống: bạn có hàng nghìn bài viết, mỗi bài trùng tên với 1 video đã tải lên HLS Manager. Đoạn dưới đây (1 tệp, bỏ vào wp-content/mu-plugins/) làm 3 việc:

  1. Đồng bộ hàng loạt: lấy các bài chưa có video, gửi 200 tiêu đề/lần tới POST /videos/lookup, lưu mã video vào meta bài; chạy bằng WP-CLI wp hls sync hoặc tự chạy mỗi giờ.
  2. Hiển thị: chèn khung phát 16:9 lên đầu nội dung bài (iframe dựng lại từ mã video, không chèn HTML lấy từ ngoài vào).
  3. Webhook: video nào vừa mã hoá xong thì gắn ngay vào bài cùng tên, video bị xoá thì gỡ.
Đã cài plugin HLS Embed (có trang cài đặt, meta box, hoàn tác) thì không cần đoạn này — dùng 1 trong 2, không bật cùng lúc.

Chạy

  • Khớp trùng hẳn tiêu đề (không phân biệt hoa thường, gộp khoảng trắng). Muốn khớp “chứa chuỗi” thì đổi 'mode' => 'contains' — dễ gắn nhầm hơn, nên kiểm vài bài trước.
  • Nhiều video cùng tiêu đề → lấy video mã hoá xong mới nhất.
  • 1 000 bài = 5 lần gọi (200/lần), xa dưới giới hạn 600 lượt/phút.
  • Ghi ngược external_id = "wp:<post_id>" lên video (cần khoá write) để sau này tra theo bài bằng by-external mà không phụ thuộc tiêu đề. Khoá read thì đặt HLS_WRITE_BACK = false.