File e Media

Archivia file e media dalla tua app. Ogni file ottiene un URL pubblico permanente.

I media in Proyecta si articolano su due livelli. La maggior parte delle app usa la funzionalità media CMS integrata — upload di immagini e file che l’AI collega automaticamente al pannello di amministrazione e ai form. Sotto di essa, una Files API di livello inferiore offre controllo diretto quando ne hai bisogno. Entrambe archiviano su object storage con CDN e restituiscono un URL pubblico permanente.

Allegati nella chat

L’input della chat accetta immagini direttamente — incolla uno screenshot o trascina un file immagine sull’input. Formati supportati: PNG, JPEG, WebP, GIF, AVIF. Dimensione massima: 10 MB per immagine.

Gli allegati della chat fanno parte del messaggio, non della tua libreria file. Per l’archiviazione persistente, usa gli upload media integrati o la Files API.

Upload media integrati (la funzionalità media CMS)

La maggior parte delle app non interagisce direttamente con la Files API — i media sono una funzionalità integrata del CMS. Il template dell’app include due hook di upload in @/hooks/useContent, che l’AI collega alla tua UI. Descrivi quello che vuoi (“un campo immagine sui miei prodotti”, “un upload file nel mio form di contatto”) e Proyecta usa quello giusto:

Hook	Dove viene usato	Endpoint	Limite dimensione
useAssetUpload()	Libreria media di amministrazione — alimenta il selettore asset nell’editor contenuti del pannello admin	POST /v1/public/files	10 MB
useFormFileUpload()	File da form pubblici — upload dei visitatori su un campo file <FormBlock/> (ricevute, foto)	POST /v1/public/uploads	5 MB

Entrambi gli hook restituiscono un url pubblico permanente che memorizzi sull’entry di contenuto (admin) o sulla submission del form (pubblico). Alcune cose da sapere:

• Entrambi i limiti sono applicati nel codice, non dal piano — 10 MB per i media admin, 5 MB per i file da form pubblici.
• I tipi accettati sono solo immagini (escluso SVG) e PDF. L’SVG viene rifiutato per motivi di sicurezza; le immagini di grandi dimensioni vengono ridimensionate automaticamente prima dell’upload.
• Non chiami questi hook direttamente — è l’AI a montarli. Ricorri alla Files API qui sotto solo per la gestione di file a basso livello o personalizzata.

La Files API

Ogni app Proyecta pubblicata può archiviare e servire file. Dalle pagine della tua app basta una singola chiamata — la procedura in più passaggi con URL firmato viene gestita per te:

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

File privati. Passa visibility: 'private' per archiviare un file fuori dal bucket pubblico, senza URL permanente. Per rileggerlo usa invece un link a breve scadenza:

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

Usa file privati + URL firmati per tutto ciò che non deve essere indovinabile — upload dei clienti, documenti d’identità, download a pagamento.

Come vengono caricati i file nella mia app?

Gli upload di file vengono gestiti tramite l’AI builder. Chiedi all’AI di costruire il flusso di upload per te:

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

L’AI collega l’upload nel codice della tua app e referenzia l’URL pubblico restituito.

FAQ

Gli URL dei file sono pubblici?

Sì. Qualsiasi file restituito dalla Files API ha un URL pubblico permanente. Non caricare nulla che non vuoi rendere accessibile.

Quanto può essere grande un file?

Le dimensioni dei file sono limitate nel codice, non dal piano: 10 MB per gli upload della libreria media admin (useAssetUpload), 5 MB per gli upload di file da form pubblici (useFormFileUpload), e 10 MB per gli allegati della chat. Gli upload media integrati accettano solo immagini (escluso SVG) e PDF.

Posso ridimensionare o ritagliare le immagini tramite URL?

Le trasformazioni immagine on-the-fly (ridimensionamento, ritaglio, conversione di formato) sono nella roadmap.

Prossimamente

• Trasformazioni immagine tramite parametri URL (ridimensionamento, ritaglio, conversione di formato)
• Organizzazione in cartelle — creazione e gestione di percorsi cartella per i file archiviati