Basic upload

Basic upload gửi toàn bộ file và metadata trong một request multipart/form-data. Phương thức này chủ yếu dành cho test và kiểm tra nhanh tích hợp. Nếu kết nối bị ngắt, upload không thể tiếp tục từ phần đã gửi.

Luồng Basic upload

Khi nên sử dụng

Test credential, namespace, metadata và luồng xử lý file của MPS.
Kiểm tra nhanh tích hợp trước khi triển khai TUS.
File nhỏ hoặc đường truyền giữa backend và MPS ổn định.
Backend muốn upload bằng HTTP client thông thường, không cần thư viện TUS.
Ứng dụng có thể gửi lại toàn bộ file khi request thất bại.

Với luồng production, MPS khuyến nghị dùng TUS resumable upload . Không gọi Basic upload trực tiếp từ browser công khai vì request phải chứa cả X-App-Credential-Id và X-App-Credential-Secret; hãy lưu hai giá trị này ở nơi bảo mật trên backend tin cậy.

Request đầy đủ

curl --request POST \
  'https://mps.mediacdn.vn/v1/namespaces/<namespace>/tus' \
  --header 'X-Auth-Type: application_credential' \
  --header 'X-App-Credential-Id: <credential-id>' \
  --header 'X-App-Credential-Secret: <credential-secret>' \
  --form 'file=@"/path/to/video.mp4"' \
  --form 'file_path=2026/09/22/video.mp4' \
  --form 'display_name=Product introduction' \
  --form 'video_profile_ids=360,480,720,1080' \
  --form 'client_reference=customer-record-42' \
  --form 'video_encryption=false' \
  --form 'default_thumb_timepct=0.25'

file là field bắt buộc. Các metadata còn lại là tùy chọn:

file_path chọn đường dẫn đích. Dùng dấu / cho thư mục và không thêm namespace vào đầu đường dẫn.
display_name là tên thân thiện hiển thị cho người quản trị.
video_profile_ids yêu cầu MPS tạo các output H.264 tương ứng. Chỉ gửi các ID profile đang bật trong namespace; ví dụ trên chỉ hợp lệ nếu cả bốn profile đã được cấu hình.
client_reference liên kết file với ID trong hệ thống của bạn và có tối đa 64 ký tự.
video_encryption đặt chính sách mã hóa riêng cho upload. Bỏ field để dùng cấu hình DRM của namespace.
default_thumb_timepct=0.25 chọn frame tại 25% thời lượng video làm thumbnail mặc định.

Response

Upload thành công trả về HTTP 200:

{
  "success": true,
  "result": {
    "upload_id": "<upload-id>",
    "display_name": "Product introduction",
    "file_path": "2026/09/22/video.mp4"
  }
}

Sau khi nhận response, video có thể vẫn đang được transcode. Dùng API liệt kê file để lấy thông tin file, playback và thumbnail khi sẵn sàng.

Xử lý lỗi

400: thiếu file hoặc metadata không hợp lệ.
401/403: credential không hợp lệ hoặc tài khoản không có quyền với namespace.
413: file vượt giới hạn 20 GiB.
500: MPS không thể lưu hoặc hoàn tất file.

Basic upload không lưu offset để tiếp tục. Với upload production, đặc biệt khi file lớn hoặc mạng không ổn định, dùng TUS resumable upload .

Upload files TUS resumable upload