文件与媒体

通过应用代码上传和管理文件。每个文件都有一个永久公开 URL。

Proyecta 通过 SDK 提供 Files API，支持在应用代码中以编程方式管理文件。

聊天附件

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

聊天附件属于消息的一部分，不会进入你的文件库。如需持久化存储，请使用 SDK。

Files API（SDK）

每个已发布的 Proyecta 应用都可以通过 Proyecta SDK 访问文件存储 API。SDK 支持列出、获取和上传文件。上传的文件会获得一个永久公开 URL，可在应用中直接引用。

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

// List files (supports limit and starting_after for pagination)
const files = await proyecta.files.list();

// Fetch a single file by ID
const file = await proyecta.files.get('1234567890123456789');
console.log(file.url); // permanent public URL

// Upload a file (two-step)
// Step 1: create a placeholder and get a signed upload URL
const { id: fileId, upload_url } = await proyecta.files.create({
    filename: 'avatar.png',
    mime_type: 'image/png',
});

// Step 2: PUT the file bytes directly to the signed URL
await fetch(upload_url, {
    method: 'PUT',
    body: fileBytes,
    headers: { 'Content-Type': 'image/png' },
});

// Step 3: finalize to get the permanent file record
const uploaded = await proyecta.files.finalize({ fileId });
console.log(uploaded.url); // permanent public URL, now populated

每个文件包含以下字段：

字段	说明
`id`	唯一标识符（数字雪花字符串）
`url`	永久公开 URL（在 finalize 步骤后填充）
`filename`	上传时的原始文件名
`mime_type`	`image/jpeg`、`application/pdf` 等
`size`	文件大小（字节）
`path`	可选的文件夹路径（例如 `/images/blog`）
`content_hash`	文件内容的 SHA-256 哈希值
`metadata`	任意键值对元数据
`created`	ISO 8601 创建时间戳
`updated`	ISO 8601 最后更新时间戳

如何在应用中实现文件上传？

文件上传功能通过 AI builder 完成。你可以让 AI 帮你搭建上传流程，例如：

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

AI 会使用 SDK 的两步上传 API 在应用代码中接好上传逻辑，并引用返回的公开 URL。你也可以直接在自己的应用代码中调用 files.create() / files.finalize()。

常见问题

文件 URL 是公开的吗？

是的。Files API 返回的所有文件都有永久公开 URL。请勿上传不希望被公开访问的内容。

单个文件的大小上限是多少？

单文件大小限制取决于你的套餐。聊天附件每张图片上限为 10 MB。

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

基于 URL 参数的即时图片变换（缩放、裁剪、格式转换）功能正在规划中。

即将推出

通过 URL 参数实现图片变换（缩放、裁剪、格式转换）
文件夹管理 —— 在面板中创建和管理文件夹路径
从文件列表中**“添加到聊天”**，将文件库中的资源直接插入 AI 对话