Файли та медіа

Зберігайте файли та медіа у своєму застосунку. Кожен файл отримує постійну публічну URL-адресу.

Медіа в Proyecta складається з двох рівнів. Більшість застосунків використовують вбудовану можливість медіа через CMS — завантаження зображень і файлів, які ШІ автоматично підключає до адмін-панелі та форм. На нижчому рівні знаходиться Files API, що надає прямий контроль у разі потреби. Обидва рівні зберігають дані в об’єктному сховищі з підтримкою CDN і повертають постійну публічну URL-адресу.

Вкладення у чаті

Поле введення чату приймає зображення безпосередньо — встав скриншот або перетягни файл зображення у поле введення. Підтримувані формати: PNG, JPEG, WebP, GIF, AVIF. Максимальний розмір: 10 МБ на зображення.

Вкладення у чаті є частиною повідомлення, а не твоєї бібліотеки файлів. Для постійного зберігання використовуй вбудовані завантаження медіа або Files API.

Вбудовані завантаження медіа (можливість медіа через CMS)

Більшість застосунків не звертаються до Files API безпосередньо — медіа є вбудованою можливістю CMS. Шаблон застосунку постачається з двома хуками для завантаження у @/hooks/useContent, і ШІ підключає їх до твого інтерфейсу. Опиши, що тобі потрібно («поле зображення для моїх товарів», «завантаження файлу у моїй контактній формі»), і Proyecta використає потрібний:

Хук	Де використовується	Endpoint	Ліміт розміру
`useAssetUpload()`	Медіабібліотека адмін-панелі — забезпечує роботу вибору медіа у редакторі контенту адмін-панелі	`POST /v1/public/files`	10 МБ
`useFormFileUpload()`	Файли публічних форм — завантаження відвідувачами через поле файлу `<FormBlock/>` (квитанції, фото)	`POST /v1/public/uploads`	5 МБ

Обидва хуки повертають постійну публічну url, яку ти зберігаєш у записі контенту (адмін) або поданні форми (публічне). Декілька важливих моментів:

Обидва ліміти задані в коді, а не тарифним планом — 10 МБ для медіа адмін-панелі, 5 МБ для публічних файлів форм.
Приймаються лише зображення (крім SVG) та PDF. SVG відхиляється з міркувань безпеки; великі зображення автоматично масштабуються перед завантаженням.
Ці хуки не викликаються напряму — їх підключає ШІ. Використовуй 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' });

Використовуй приватні файли й підписані посилання для всього, що не має бути вгадуваним, — завантаження клієнтів, документи, платні матеріали для скачування.

Як файли завантажуються до мого застосунку?

Завантаження файлів виконується через AI builder. Попроси ШІ створити потрібний flow завантаження:

"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"

ШІ підключає завантаження у коді твого застосунку і посилається на повернуту публічну URL-адресу.

Часті запитання

Чи є URL-адреси файлів публічними?

Так. Будь-який файл, повернутий Files API, має постійну публічну URL-адресу. Не завантажуй нічого, що не має бути загальнодоступним.

Яким може бути максимальний розмір файлу?

Ліміти розміру файлів задані в коді, а не тарифним планом: 10 МБ для завантажень медіабібліотеки адмін-панелі (useAssetUpload), 5 МБ для завантажень файлів через публічні форми (useFormFileUpload) та 10 МБ для вкладень у чаті. Вбудовані завантаження медіа приймають лише зображення (крім SVG) та PDF.

Чи можна змінити розмір або обрізати зображення за URL-адресою?

Перетворення зображень на льоту (зміна розміру, обрізка, конвертація формату) заплановані на майбутнє.

Незабаром

Трансформації зображень через параметри URL (зміна розміру, обрізка, конвертація формату)
Організація папок — створення та керування шляхами до папок для збережених файлів