Tệp & Phương tiện

Lưu trữ tệp và phương tiện từ ứng dụng của bạn. Mỗi tệp đều có URL công khai vĩnh viễn.

Phương tiện trong Proyecta hoạt động theo hai lớp. Hầu hết các ứng dụng sử dụng tính năng phương tiện CMS tích hợp sẵn — tải lên hình ảnh và tệp được AI kết nối vào bảng quản trị và biểu mẫu cho bạn. Bên dưới đó, Files API cấp thấp hơn cho phép bạn kiểm soát trực tiếp khi cần. Cả hai đều lưu trữ vào object storage có CDN hỗ trợ và trả về URL công khai vĩnh viễn.

Tệp đính kèm trong chat

Ô nhập chat chấp nhận hình ảnh trực tiếp — dán ảnh chụp màn hình hoặc kéo tệp hình ảnh vào ô nhập. Các định dạng được hỗ trợ: PNG, JPEG, WebP, GIF, AVIF. Kích thước tối đa: 10 MB mỗi hình ảnh.

Tệp đính kèm trong chat là một phần của tin nhắn, không thuộc thư viện tệp của bạn. Để lưu trữ lâu dài, hãy sử dụng tính năng tải lên phương tiện tích hợp sẵn hoặc Files API.

Tải lên phương tiện tích hợp sẵn (tính năng phương tiện CMS)

Hầu hết các ứng dụng không cần dùng trực tiếp Files API — phương tiện là tính năng CMS tích hợp sẵn. Template ứng dụng đi kèm hai upload hook trong @/hooks/useContent, và AI kết nối chúng vào giao diện của bạn. Bạn mô tả những gì bạn muốn (“một trường hình ảnh cho sản phẩm của tôi”, “tải lên tệp trên biểu mẫu liên hệ của tôi”) và Proyecta sẽ dùng hook phù hợp:

Hook	Nơi sử dụng	Endpoint	Giới hạn kích thước
useAssetUpload()	Thư viện phương tiện quản trị — hỗ trợ bộ chọn tài sản trong trình chỉnh sửa nội dung của bảng quản trị	POST /v1/public/files	10 MB
useFormFileUpload()	Tệp biểu mẫu công khai — tệp tải lên của khách truy cập trên trường tệp <FormBlock/> (hóa đơn, ảnh)	POST /v1/public/uploads	5 MB

Cả hai hook đều trả về url công khai vĩnh viễn mà bạn lưu vào mục nội dung (quản trị) hoặc lần gửi biểu mẫu (công khai). Một số điều cần lưu ý:

• Cả hai giới hạn đều được áp dụng trong code, không phải theo gói — 10 MB cho phương tiện quản trị, 5 MB cho tệp biểu mẫu công khai.
• Chỉ chấp nhận hình ảnh (ngoại trừ SVG) và PDF. SVG bị từ chối vì lý do bảo mật; hình ảnh lớn sẽ tự động được thu nhỏ trước khi tải lên.
• Bạn không cần gọi trực tiếp những hook này — AI sẽ gắn kết chúng. Chỉ dùng Files API bên dưới khi cần xử lý tệp ở cấp thấp hơn hoặc theo cách tùy chỉnh.

Files API

Mọi ứng dụng Proyecta đã publish đều có thể lưu trữ và phục vụ tệp. Từ các trang của ứng dụng, đây chỉ là một lời gọi duy nhất — toàn bộ quy trình tải lên có chữ ký nhiều bước đã được xử lý sẵn cho bạn:

import * as platform from '@/lib/platformClient.ts';

// Upload straight from a file input — one call, no signed-URL juggling
async function onPick(file: File) {
    const asset = await platform.assetDirectUpload({
        blob: file,
        filename: file.name,
        mimeType: file.type,
    });
    console.log(asset.url); // permanent public URL
}

// List what's stored
const { assets, hasMore } = await platform.assetList({ limit: 20 });

// Remove one
await platform.assetDelete(asset.id);

Tệp riêng tư. Truyền visibility: 'private' để lưu tệp ngoài bucket công khai, không có URL vĩnh viễn. Thay vào đó, hãy đọc lại tệp bằng một liên kết có thời hạn ngắn:

const { url, expiresAt } = await platform.assetSignedUrl(asset.id, { variant: 'thumbnail' });

Hãy dùng tệp riêng tư + URL có chữ ký cho bất cứ thứ gì không nên đoán được — tệp khách hàng tải lên, giấy tờ tùy thân, nội dung tải về đã trả phí.

Làm thế nào để tải tệp lên ứng dụng của tôi?

Việc tải tệp lên được xử lý thông qua AI builder. Hãy yêu cầu AI xây dựng luồng tải lên cho bạn:

• "Cho phép người dùng tải lên ảnh đại diện và lưu vào Proyecta Files"
• "Thêm thư viện ảnh để người dùng đã đăng nhập có thể tải lên và xem ảnh của họ"
• "Cho phép tôi đính kèm hóa đơn PDF vào các đơn hàng"

AI sẽ kết nối luồng tải lên trong code ứng dụng của bạn và tham chiếu URL công khai được trả về.

Câu hỏi thường gặp

Các URL tệp có công khai không?

Có. Mọi tệp được trả về bởi Files API đều có URL công khai vĩnh viễn. Đừng tải lên bất kỳ thứ gì mà bạn không muốn công khai.

Tệp có thể lớn đến mức nào?

Kích thước tệp bị giới hạn trong code, không theo gói: 10 MB cho tải lên thư viện phương tiện quản trị (useAssetUpload), 5 MB cho tải lên tệp biểu mẫu công khai (useFormFileUpload), và 10 MB cho tệp đính kèm trong chat. Tải lên phương tiện tích hợp sẵn chỉ chấp nhận hình ảnh (ngoại trừ SVG) và PDF.

Tôi có thể thay đổi kích thước hoặc cắt xén hình ảnh qua URL không?

Tính năng chuyển đổi hình ảnh theo thời gian thực (thay đổi kích thước, cắt xén, chuyển đổi định dạng) đang trong lộ trình phát triển.

Sắp ra mắt

• Chuyển đổi hình ảnh thông qua tham số URL (thay đổi kích thước, cắt xén, chuyển đổi định dạng)
• Tổ chức thư mục — tạo và quản lý đường dẫn thư mục cho các tệp đã lưu trữ