Файлы и медиа

Храните файлы и медиа из вашего приложения. Каждый файл получает постоянный публичный URL.

Работа с медиа в Proyecta устроена в двух уровнях. Большинство приложений используют встроенную возможность CMS для работы с медиа — загрузку изображений и файлов, которую AI автоматически подключает к вашей панели администратора и формам. Под ней находится низкоуровневый Files API, дающий прямой контроль, когда это необходимо. Оба варианта хранят данные в объектном хранилище с CDN и возвращают постоянный публичный URL.

Вложения в чате

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

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

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

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

Хук	Где используется	Endpoint	Лимит размера
useAssetUpload()	Медиабиблиотека администратора — обеспечивает работу выбора ресурсов в редакторе контента панели администратора	POST /v1/public/files	10 МБ
useFormFileUpload()	Публичные файлы форм — загрузка файлов посетителями в поле файла <FormBlock/> (квитанции, фотографии)	POST /v1/public/uploads	5 МБ

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

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

Используйте приватное хранение и подписанные ссылки для всего, что не должно подбираться перебором: загрузки клиентов, документы, удостоверяющие личность, платные файлы для скачивания.

Как загружать файлы в моё приложение?

Загрузка файлов осуществляется через 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 подключает загрузку в коде вашего приложения и ссылается на возвращённый публичный URL.

Часто задаваемые вопросы

Являются ли URL файлов публичными?

Да. Любой файл, возвращаемый Files API, имеет постоянный публичный URL. Не загружайте ничего, что не должно быть общедоступным.

Каков максимальный размер файла?

Размеры файлов ограничены в коде, а не планом: 10 МБ для загрузок в медиабиблиотеку администратора (useAssetUpload), 5 МБ для публичных файлов форм (useFormFileUpload) и 10 МБ для вложений в чате. Встроенная загрузка медиа принимает только изображения (кроме SVG) и PDF.

Можно ли изменять размер или обрезать изображения по URL?

Трансформации изображений на лету (изменение размера, обрезка, конвертация формата) включены в roadmap.

Скоро

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