فایل‌ها و رسانه

فایل‌ها را از کد اپلیکیشن خود آپلود و مدیریت کنید. هر فایل یک URL عمومی دائمی دریافت می‌کند.

Proyecta یک Files API از طریق SDK برای مدیریت برنامه‌نویسی فایل‌ها از کد اپلیکیشن شما فراهم می‌کند.

پیوست‌های چت

ورودی چت مستقیماً تصاویر را می‌پذیرد — یک اسکرین‌شات paste کنید یا یک فایل تصویری را روی ورودی بکشید و رها کنید. فرمت‌های پشتیبانی‌شده: PNG، JPEG، WebP، GIF، AVIF. حداکثر اندازه: ۱۰ مگابایت به ازای هر تصویر.

پیوست‌های چت بخشی از پیام هستند، نه کتابخانه فایل شما. برای ذخیره‌سازی دائمی، از 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	شناسه یکتا (رشته عددی snowflake)
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 بخواهید جریان آپلود را برایتان بسازد:

• "Let users upload a profile photo and store it in Proyecta Files"
• "Add an image gallery where signed-in users can upload and view their photos"
• "Let me attach PDF invoices to orders"

AI با استفاده از two-step upload API مربوط به SDK، آپلود را در کد اپلیکیشن شما سیم‌کشی می‌کند و به URL عمومی بازگشتی ارجاع می‌دهد. همچنین می‌توانید files.create() / files.finalize() را مستقیماً از کد اپلیکیشن خودتان فراخوانی کنید.

سؤالات متداول

آیا URL فایل‌ها عمومی هستند؟

بله. هر فایلی که توسط Files API بازگردانده می‌شود یک URL عمومی دائمی دارد. چیزی که نمی‌خواهید در معرض دید باشد را آپلود نکنید.

یک فایل می‌تواند چقدر بزرگ باشد؟

محدودیت‌های هر فایل به پلن شما بستگی دارد. پیوست‌های چت به ۱۰ مگابایت به ازای هر تصویر محدود هستند.

آیا می‌توانم تصاویر را از طریق URL تغییر اندازه یا برش دهم؟

تبدیل‌های تصویری on-the-fly (تغییر اندازه، برش، تبدیل فرمت) در roadmap قرار دارند.

به زودی

• تبدیل‌های تصویری از طریق پارامترهای URL (تغییر اندازه، برش، تبدیل فرمت)
• سازماندهی پوشه‌ای — ایجاد و مدیریت مسیرهای پوشه در پنل
• “Add to Chat” از ردیف یک فایل، تا asset‌های کتابخانه بتوانند در مکالمه AI رها شوند