Skip to main content
POST
Tải nội dung đa phương tiện lên qua URL đã ký
Endpoint này là đích đến của URL POST đã ký do MCP request-media-upload-tool cấp. Nhờ đó, AI agent và ứng dụng của agent có thể tải tệp cục bộ lên không gian làm việc mà không cần cấp Personal Access Token; chính URL đã ký đóng vai trò xác thực. Thông thường, bạn không gọi trực tiếp endpoint này. Luồng xử lý như sau:
  1. AI agent gọi request-media-upload-tool và nhận upload_url cùng upload_token
  2. Agent hoặc người dùng gửi tệp bằng POST tới upload_url
  3. AI agent gọi attach-media-from-upload-tool với cùng upload_token để gắn Media vừa tạo vào bài đăng
Nếu đã có Personal Access Token, bạn có thể dùng endpoint đơn giản hơn là POST /posts/{post}/media để tải trực tiếp lên một bài đăng mà không cần URL đã ký.

Tham số đường dẫn

string
bắt buộc
UUID dùng một lần được request-media-upload-tool nhúng vào URL đã ký. Phải là UUID hợp lệ; giá trị không phải UUID sẽ trả về 404.

Tham số truy vấn (do URL đã ký thêm vào)

Các tham số này được URL::temporarySignedRoute của Laravel thêm vào URL và bảo vệ bằng chữ ký HMAC. Bạn không được tự đặt chúng.
string
bắt buộc
Không gian làm việc nhận tệp tải lên. Việc sửa giá trị này sẽ làm chữ ký mất hiệu lực và endpoint trả về 403.
integer
bắt buộc
Unix timestamp khi URL hết hạn. TTL mặc định là 15 phút kể từ lúc cấp URL (có thể cấu hình qua MCP_UPLOAD_URL_TTL_MINUTES).
string
bắt buộc
HMAC-SHA256 của URL và tham số truy vấn, được ký bằng APP_KEY của ứng dụng. Middleware signed của Laravel kiểm tra chữ ký trước khi controller chạy.

Yêu cầu

Gửi dưới dạng multipart/form-data với một trường media.
file
bắt buộc
Tệp cần tải lên. Luồng MCP có giới hạn cứng 50 MB (cấu hình qua MCP_UPLOAD_MAX_SIZE_MB) và chỉ chấp nhận các loại MIME sau:
  • Ảnh: image/jpeg, image/png, image/gif, image/webp
  • Video: video/mp4, video/quicktime (MOV)
Loại MIME được phát hiện từ magic bytes của tệp, không dựa vào phần mở rộng hay header Content-Type. Vì vậy, đổi tên evil.exe thành photo.png cũng không vượt qua được danh sách cho phép.

Xác thực

Không cần Bearer token. URL đã ký chính là thông tin xác thực.
  • Middleware signed xác minh HMAC bằng APP_KEY và từ chối URL hết hạn với mã 403.
  • Cache::add nguyên tử cùng ràng buộc UNIQUE trên media.upload_token bảo đảm URL chỉ dùng một lần. Yêu cầu POST thứ hai với cùng token sẽ nhận 409.
  • Endpoint giới hạn 10 yêu cầu mỗi phút cho mỗi IP để giảm thiểu nguy cơ URL bị lộ và lạm dụng.

Cách hoạt động

  • Tệp được lưu tại medias/{uuid}.{ext} trên ổ lưu trữ đã cấu hình (local, s3, r2…). Đường dẫn do máy chủ tạo; tên tệp từ máy khách không được dùng trong đường dẫn.
  • Ảnh tĩnh PNG và WebP được chuẩn hóa thành JPEG (q100) để tương thích với mọi nền tảng. GIF được giữ nguyên, gồm cả chuyển động trên X, Bluesky và Mastodon. Video được lưu nguyên bản.
  • Bản ghi Media mới được gắn upload_token để AI agent tham chiếu qua attach-media-from-upload-tool. Media được tạo dưới dạng tài nguyên của không gian làm việc, chưa gắn với bài đăng nào.
  • Luồng POST /posts/{post}/media không gọi endpoint này. Endpoint chỉ xử lý URL đã ký do MCP cấp.

Phản hồi

string
Trả lại tham số đường dẫn {token} để ứng dụng tiện sử dụng.
string
UUID của bản ghi Media vừa tạo. Truyền giá trị này (hoặc upload_token) vào attach-media-from-upload-tool để gắn vào bài đăng.
string
image hoặc video.
string
Loại MIME được phát hiện. Lưu ý: đầu vào PNG/WebP được báo là image/jpeg do bước chuẩn hóa.
string
Tên tệp do máy khách gửi (chỉ lưu trong metadata, không bao giờ dùng làm đường dẫn lưu trữ). path).

Mã trạng thái