Tải ảnh lên cho trợ lý
Lưu một ảnh để một lượt chat sau đó có thể đính kèm bằng id.
Cùng scope với /agent/chat-messages, cùng quy tắc: chỉ có trên key đã được gán 1 trợ lý, không thể tự chọn. Thiếu scope → 403 INSUFFICIENT_SCOPE; key mất ràng buộc → 403 ASSISTANT_NOT_BOUND.
Upload: multipart/form-data với phần file (ảnh) và trường user.
user phải khớp với userId bạn dùng khi chat. File được gắn với tenant của bạn và với đúng người dùng cuối đó — một lượt chat gửi với userId khác sẽ không đính kèm được file này.
Điều được kiểm tra: loại file thật được nhận diện từ magic bytes, nên một file thực thi đổi tên thành .png vẫn bị từ chối với 400, cũng như file vượt quá 5 MB. Loại file bạn khai báo trong phần multipart chỉ mang tính tham khảo.
Không tính phí riêng. Việc lưu trữ hiện chưa được đo tính phí; chỉ lượt chat có đính kèm ảnh mới bị tính phí.
Retry. Endpoint này KHÔNG idempotent — gửi lại một upload sẽ lưu thêm 1 bản sao và trả về id khác. Chỉ gửi lại khi thật sự không nhận được response.
Headers
Request
Ảnh. Tối đa 5 MB. Định dạng cho phép: PNG, JPEG, WebP, GIF — được nhận diện từ magic bytes của file, không dựa vào phần mở rộng hay content type khai báo, nên đổi tên file không qua được kiểm tra này.
ID CỦA BẠN cho người dùng cuối của bạn. PHẢI khớp với userId bạn gửi ở POST /agent/chat-messages; file được gắn với id này, một lượt chat gửi với userId khác không đính kèm được. Cùng quy tắc như userId: một định danh KHÔNG MANG NGHĨA, không dùng email, số điện thoại, hay tên thật — được lưu nguyên văn dưới dạng plain text.
Response
Ảnh đã được lưu.
Handle của file đã lưu. Giữ lại giá trị này — đây là thứ một lượt chat sau đó gửi lên để đính kèm ảnh. Quyền sở hữu được kiểm tra lại mỗi lần dùng, nên chỉ có id không tự cấp quyền gì.
Tên file gốc bạn đã upload.
Dung lượng đã lưu (byte).
Loại nhận diện được từ magic bytes của file — không phải loại bạn khai báo.
Thời điểm upload, dạng ISO-8601.
Phần mở rộng viết thường không kèm dấu chấm, hoặc "" nếu tên không có.
Link để bên đối tác đọc lại file, suy ra từ object key đã lưu. Là URL tuyệt đối khi hệ thống có cấu hình base URL đọc file — object key nội bộ không bao giờ bị lộ ra ngoài.