文件与媒体

从你的应用中存储文件和媒体。每个文件都有一个永久的公开 URL。

Proyecta 中的媒体分为两个层次。大多数应用使用内置 CMS 媒体功能——图片和文件上传由 AI 自动接入你的管理面板和表单。在此之下，还有更底层的 Files API，在需要时可进行直接控制。两者都存储到 CDN 支持的对象存储中，并返回一个永久的公开 URL。

聊天附件

聊天输入框支持直接粘贴截图或将图片文件拖入。支持的格式：PNG、JPEG、WebP、GIF、AVIF。每张图片的最大大小：10 MB。

聊天附件是消息的一部分，不属于你的文件库。如需持久存储，请使用内置媒体上传功能或 Files API。

内置媒体上传（CMS 媒体功能）

大多数应用不需要直接调用 Files API——媒体是内置的 CMS 功能。应用模板在 @/hooks/useContent 中内置了两个上传 hook，AI 会自动将它们接入你的 UI。你只需描述需求（“在我的产品上添加一个图片字段”、“在我的联系表单上添加文件上传”），Proyecta 会自动选择合适的 hook：

Hook	使用场景	接口端点	大小限制
`useAssetUpload()`	管理员媒体库——为管理面板内容编辑器中的资产选择器提供支持	`POST /v1/public/files`	10 MB
`useFormFileUpload()`	公开表单文件——访客在 `<FormBlock/>` 文件字段上传（收据、照片等）	`POST /v1/public/uploads`	5 MB

两个 hook 均返回一个永久公开的 url，你可以将其存储在内容条目（管理员）或表单提交记录（公开）中。有几点需要了解：

两个大小限制均通过代码强制执行，与套餐无关——管理员媒体为 10 MB，公开表单文件为 5 MB。
仅接受图片（SVG 除外）和 PDF。 SVG 出于安全原因被拒绝；较大的图片在上传前会自动缩小。
你无需直接调用这些 hook——AI 会自动挂载它们。仅在需要更底层或自定义的文件处理时，才使用下方的 Files API。

Files API

每个已发布的 Proyecta 应用都可以存储并提供文件。在应用页面中，这只需一次调用——多步签名上传流程已经为你封装好了：

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);

私有文件。 传入 visibility: 'private' 可将文件存放在公开存储桶之外，且不生成永久 URL。读取时改用短期有效的链接：

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

对于任何不应被猜到的内容——顾客上传的文件、身份证件、付费下载资源——都请使用私有存储 + 签名 URL。

如何将文件上传到我的应用？

文件上传通过 AI builder 来处理。你可以直接让 AI 为你构建上传流程：

"让用户上传个人头像并存储到 Proyecta Files"
"添加一个图片画廊，让已登录用户可以上传和查看自己的照片"
"允许我将 PDF 发票附加到订单上"

AI 会在你的应用代码中接入上传功能，并引用返回的公开 URL。

常见问题

文件 URL 是公开的吗？

是的。Files API 返回的每个文件都有一个永久公开 URL。请勿上传任何不希望对外公开的内容。

文件大小上限是多少？

文件大小通过代码限制，与套餐无关：管理员媒体库上传（useAssetUpload）为 10 MB，公开表单文件上传（useFormFileUpload）为 5 MB，聊天附件为 10 MB。内置媒体上传仅接受图片（SVG 除外）和 PDF。

能通过 URL 对图片进行缩放或裁剪吗？

动态图片变换（缩放、裁剪、格式转换）已在路线图中。

即将推出

图片变换——通过 URL 参数实现（缩放、裁剪、格式转换）
文件夹管理——创建和管理已存储文件的文件夹路径