Arquivos e Mídia

Armazene arquivos e mídias do seu app. Cada arquivo recebe uma URL pública permanente.

A mídia no Proyecta funciona em duas camadas. A maioria dos apps utiliza a capacidade de mídia integrada ao CMS — uploads de imagens e arquivos que a IA conecta automaticamente ao seu painel de administração e formulários. Por baixo disso, uma API de Arquivos de nível mais baixo oferece controle direto quando necessário. Ambas armazenam em object storage com CDN e retornam uma URL pública permanente.

Anexos no chat

A entrada do chat aceita imagens diretamente — cole um screenshot ou arraste um arquivo de imagem para a entrada. Formatos suportados: PNG, JPEG, WebP, GIF, AVIF. Tamanho máximo: 10 MB por imagem.

Anexos do chat fazem parte da mensagem, não da sua biblioteca de arquivos. Para armazenamento persistente, use os uploads de mídia integrados ou a API de Arquivos.

Uploads de mídia integrados (a capacidade de mídia do CMS)

A maioria dos apps não acessa a API de Arquivos diretamente — mídia é uma capacidade integrada ao CMS. O template do app inclui dois hooks de upload em @/hooks/useContent, e a IA os conecta à sua interface. Você descreve o que quer (“um campo de imagem nos meus produtos”, “um upload de arquivo no meu formulário de contato”) e o Proyecta usa o correto:

Hook	Onde é usado	Endpoint	Limite de tamanho
useAssetUpload()	Biblioteca de mídia do admin — suporta o seletor de assets no editor de conteúdo do painel de administração	POST /v1/public/files	10 MB
useFormFileUpload()	Arquivos de formulários públicos — uploads de visitantes em um campo de arquivo <FormBlock/> (recibos, fotos)	POST /v1/public/uploads	5 MB

Ambos os hooks retornam uma url pública permanente que você armazena na entrada de conteúdo (admin) ou no envio do formulário (público). Algumas informações importantes:

• Ambos os limites são aplicados no código, não por plano — 10 MB para mídia do admin, 5 MB para arquivos de formulários públicos.
• Os tipos aceitos são apenas imagens (exceto SVG) e PDF. SVG é rejeitado por segurança; imagens grandes são automaticamente reduzidas antes do upload.
• Você não chama esses hooks diretamente — a IA os configura. Use a API de Arquivos abaixo apenas para manipulação de arquivos de nível mais baixo ou personalizada.

A API de Arquivos

Todo app publicado no Proyecta pode armazenar e servir arquivos. Nas páginas do seu app isso é uma única chamada — a dança de upload assinado em várias etapas é resolvida para você:

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

Arquivos privados. Passe visibility: 'private' para armazenar um arquivo fora do bucket público, sem URL permanente. Leia-o de volta com um link de curta duração:

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

Use privado + URLs assinadas para qualquer coisa que não deva ser adivinhável — uploads de clientes, documentos de identidade, downloads pagos.

Como os arquivos são enviados para o meu app?

Os uploads de arquivos são gerenciados pelo AI builder. Peça à IA para criar o fluxo de upload para você:

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

A IA configura o upload no código do seu app e referencia a URL pública retornada.

Perguntas frequentes

As URLs dos arquivos são públicas?

Sim. Qualquer arquivo retornado pela API de Arquivos possui uma URL pública permanente. Não faça upload de nada que você não queira exposto.

Qual é o tamanho máximo de um arquivo?

Os tamanhos de arquivo são limitados no código, não por plano: 10 MB para uploads na biblioteca de mídia do admin (useAssetUpload), 5 MB para uploads de arquivos em formulários públicos (useFormFileUpload) e 10 MB para anexos no chat. Os uploads de mídia integrados aceitam apenas imagens (exceto SVG) e PDF.

Posso redimensionar ou recortar imagens pela URL?

Transformações de imagens em tempo real (redimensionamento, recorte, conversão de formato) estão no roadmap.

Em breve

• Transformações de imagens via parâmetros de URL (redimensionamento, recorte, conversão de formato)
• Organização em pastas — crie e gerencie caminhos de pastas para os arquivos armazenados