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.
/api/v1Gọi thử trong 1 phút
- 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.
- Gọi danh sách video đã xong (thay
KHOA_APIbằ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 |
|---|---|
| read | Mọ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:
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:
| HTTP | code | Khi nào |
|---|---|---|
| 400 | invalid_request | Thiế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. |
| 401 | missing_api_key | Không gửi khoá (hoặc gửi ?key= cho yêu cầu không phải GET). |
| 401 | invalid_api_key | Khoá sai hoặc đã bị thu hồi. |
| 401 | api_key_disabled | Khoá đang bị tắt ở trang quản lý. |
| 403 | insufficient_scope | Khoá chỉ đọc gọi endpoint ghi/webhook. |
| 404 | video_not_found | Khô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. |
| 409 | not_ready | Lấy mã nhúng khi video chưa done. |
| 409 | external_id_exists | external_id đã gắn video khác. |
| 409 | busy · no_source | Mã 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). |
| 429 | rate_limited | Vượt giới hạn lượt — chờ Retry-After giây. |
| 500 · 507 | server_error · insufficient_storage | Lỗ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 — đừngjson_decoderồ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-Deliverygiữ 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_atcũ 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:
- Đồ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-CLIwp hls synchoặc tự chạy mỗi giờ. - 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).
- 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ỡ.
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ì đặtHLS_WRITE_BACK=false.