Upload files
Trước khi upload, hãy chọn phương thức phù hợp với môi trường chạy ứng dụng, kích thước file và độ ổn định của đường truyền. MPS hỗ trợ ba chiến lược qua cùng collection endpoint:
POST https://mps.mediacdn.vn/v1/namespaces/{namespace}/tus
Các phương thức upload
| Chiến lược | Phù hợp với | Có thể tiếp tục? | Credential |
|---|---|---|---|
| Basic upload | Chủ yếu để test và kiểm tra nhanh tích hợp từ backend | Không | Chỉ trên backend |
| TUS resumable (Khuyến nghị) | Backend/worker production | Có | Chỉ trên backend/worker |
| Direct TUS upload (Khuyến nghị) | Browser hoặc mobile app upload file của end user | Có | Chỉ backend tạo upload URL |
Giới hạn upload
- Kích thước tối đa của một upload là 20 GiB.
- Phiên TUS hết hạn sau 24 giờ.
- Basic upload không thể tiếp tục sau khi request bị ngắt; TUS có thể tiếp tục từ
Upload-Offsetđã lưu. - File hoàn tất được xử lý theo cấu hình namespace. Với namespace liên kết VoD, chỉ file video được đồng bộ và hiển thị trên dashboard VoD. Hình ảnh và các loại file khác chỉ được quản lý qua API MPS.
Định dạng được hỗ trợ
MPS lưu trữ được hầu hết mọi loại file. MPS nhận diện loại file không phân biệt chữ hoa/chữ thường dựa trên extension trong file_path.
Video: MP4, MKV, MOV, AVI, FLV, MTS, PS, MXF, LXF, GXF, 3GP, WebM, MPG và TS. Các định dạng này được phân loại là video và kích hoạt transcoding sau khi upload hoàn tất.
Hình ảnh: PNG, GIF, JPG/JPEG, WebP, SVG và HEIC. Các định dạng này được phân loại là hình ảnh, lưu bản gốc và hỗ trợ xử lý on-the-fly.
Các extension khác được lưu như file thông thường. Hình ảnh và file thông thường vẫn được liệt kê, quản lý qua API MPS nhưng không được đồng bộ lên dashboard VoD.
Khuyến nghị cho video theo yêu cầu
- Ưu tiên container MP4 với video H.264 và audio AAC để đạt khả năng tương thích phát rộng.
- Giữ nguyên frame rate của nội dung gốc trước khi upload; tránh chuyển đổi frame rate không cần thiết.
- Chọn
video_profile_idsdựa trên chất lượng nguồn và các profile đang bật trong namespace. - Dùng TUS resumable cho upload production từ backend/worker; dùng Direct TUS upload cho browser/mobile app của end user. Basic upload chủ yếu dành cho test và kiểm tra nhanh tích hợp.
- Dùng
client_referenceổn định để liên kết file với dữ liệu nghiệp vụ của bạn.
Metadata (Upload option) được hỗ trợ
Các trang chi tiết có ví dụ đầy đủ cho từng phương thức.
| Trường | Kiểu | Bắt buộc | Hành vi |
|---|---|---|---|
file_path |
string | Không | Đường dẫn tương đối trong namespace, ví dụ 2026/09/22/video.mp4. Nếu bỏ trống, MPS tạo tên mặc định từ upload ID. |
display_name |
string | Không | Tên hiển thị trên dữ liệu file; với file video trong namespace liên kết VoD, giá trị này cũng hiển thị trên dashboard VoD. |
video_profile_ids |
string | Không | Danh sách ID profile H.264 phân tách bằng dấu phẩy. Mỗi profile phải tồn tại, đang bật và thuộc namespace. |
client_reference |
string | Không | Mã tham chiếu do ứng dụng quản lý, tối đa 64 ký tự; hỗ trợ truy vấn chính xác và phân biệt hoa thường. |
video_encryption |
boolean | Không | Bật/tắt mã hóa video. Nếu bỏ trống, MPS dùng cấu hình DRM của namespace. |
default_thumb_timepct |
number | Không | Vị trí thumbnail theo tỷ lệ thời lượng video, từ 0.0 đến 1.0; mặc định 0. |
Với Basic upload, metadata là các field của multipart/form-data. Với TUS, tus-js-client tự chuyển object metadata thành header Upload-Metadata và Base64-encode từng giá trị.