Pliki i multimedia

Przechowuj pliki i multimedia w swojej aplikacji. Każdy plik otrzymuje trwały publiczny adres URL.

Multimedia w Proyecta działają na dwóch poziomach. Większość aplikacji korzysta z wbudowanej funkcji mediów CMS — przesyłania obrazów i plików, które AI automatycznie integruje z panelem administracyjnym i formularzami. Pod spodem znajduje się niskopoziomowe API plików, które daje ci bezpośrednią kontrolę, gdy jej potrzebujesz. Oba rozwiązania przechowują pliki w object storage z CDN i zwracają trwały publiczny adres URL.

Załączniki w czacie

Pole tekstowe czatu przyjmuje obrazy bezpośrednio — wklej zrzut ekranu lub przeciągnij plik graficzny na pole. Obsługiwane formaty: PNG, JPEG, WebP, GIF, AVIF. Maksymalny rozmiar: 10 MB na obraz.

Załączniki w czacie są częścią wiadomości, a nie biblioteki plików. Aby trwale przechowywać pliki, korzystaj z wbudowanych przesyłań mediów lub API plików.

Wbudowane przesyłanie mediów (funkcja mediów CMS)

Większość aplikacji nie korzysta bezpośrednio z API plików — media są wbudowaną funkcją CMS. Szablon aplikacji zawiera dwa hooki do przesyłania w @/hooks/useContent, a AI integruje je z twoim interfejsem. Opisz, czego potrzebujesz („pole na obraz przy produktach“, „przesyłanie pliku w formularzu kontaktowym“), a Proyecta użyje odpowiedniego hooka:

Hook	Gdzie jest używany	Endpoint	Limit rozmiaru
useAssetUpload()	Biblioteka mediów w panelu administracyjnym — obsługuje selektor zasobów w edytorze treści panelu admina	POST /v1/public/files	10 MB
useFormFileUpload()	Pliki z publicznych formularzy — przesyłanie przez odwiedzających w polu pliku <FormBlock/> (paragony, zdjęcia)	POST /v1/public/uploads	5 MB

Oba hooki zwracają trwały publiczny adres url, który zapisujesz we wpisie treści (admin) lub zgłoszeniu formularza (publiczny). Kilka ważnych informacji:

• Oba limity są egzekwowane w kodzie, nie przez plan — 10 MB dla mediów administracyjnych, 5 MB dla publicznych plików z formularzy.
• Akceptowane są wyłącznie obrazy (z wyjątkiem SVG) i pliki PDF. SVG jest odrzucany ze względów bezpieczeństwa; duże obrazy są automatycznie skalowane przed przesłaniem.
• Nie wywołujesz tych hooków bezpośrednio — montuje je AI. Po niskopoziomową lub niestandardową obsługę plików sięgaj po API plików opisane poniżej.

API plików

Każda opublikowana aplikacja Proyecta może przechowywać i udostępniać pliki. Ze stron aplikacji jest to pojedyncze wywołanie — wieloetapowy taniec z podpisanym przesyłaniem jest obsługiwany za ciebie:

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

Pliki prywatne. Przekaż visibility: 'private', aby zapisać plik poza publicznym bucketem, bez trwałego adresu URL. Odczytasz go zamiast tego przez krótko żyjący link:

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

Używaj trybu prywatnego i podpisanych adresów URL do wszystkiego, czego nie da się zgadywać — plików przesyłanych przez klientów, dokumentów tożsamości, płatnych plików do pobrania.

Jak przesyłać pliki do mojej aplikacji?

Przesyłanie plików odbywa się przez AI builder. Poproś AI, aby zbudowała dla ciebie przepływ przesyłania:

• "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 integruje przesyłanie w kodzie twojej aplikacji i odwołuje się do zwróconego publicznego adresu URL.

Najczęstsze pytania

Czy adresy URL plików są publiczne?

Tak. Każdy plik zwrócony przez API plików ma trwały publiczny adres URL. Nie przesyłaj niczego, czego nie chcesz ujawniać publicznie.

Jak duży może być plik?

Limity rozmiaru plików są egzekwowane w kodzie, nie przez plan: 10 MB dla przesyłania do biblioteki mediów w panelu admina (useAssetUpload), 5 MB dla publicznych plików z formularzy (useFormFileUpload) oraz 10 MB dla załączników w czacie. Wbudowane przesyłanie mediów akceptuje wyłącznie obrazy (z wyjątkiem SVG) i pliki PDF.

Czy mogę zmieniać rozmiar lub przycinać obrazy przez adres URL?

Dynamiczne transformacje obrazów (zmiana rozmiaru, przycinanie, konwersja formatu) są w planach rozwoju.

Wkrótce

• Transformacje obrazów przez parametry URL (zmiana rozmiaru, przycinanie, konwersja formatu)
• Organizacja folderów — tworzenie i zarządzanie ścieżkami folderów dla przechowywanych plików