Dosyalar & Medya

Uygulamanızdan dosya ve medya depolayın. Her dosya kalıcı bir herkese açık URL alır.

Proyecta’da medya iki katmanda gelir. Çoğu uygulama yerleşik CMS medya özelliğini kullanır — AI’ın yönetici panelinize ve formlarınıza otomatik olarak bağladığı görsel ve dosya yüklemeleri. Bunun altında, ihtiyaç duyduğunuzda doğrudan kontrol sağlayan daha düşük seviyeli bir Files API yer alır. Her ikisi de CDN destekli nesne depolamaya kaydeder ve kalıcı bir herkese açık URL döndürür.

Sohbet ekleri

Sohbet girişi görselleri doğrudan kabul eder — bir ekran görüntüsü yapıştırın ya da girişe bir görsel dosyası sürükleyin. Desteklenen formatlar: PNG, JPEG, WebP, GIF, AVIF. Maksimum boyut: görsel başına 10 MB.

Sohbet ekleri mesajın bir parçasıdır, dosya kitaplığınıza ait değildir. Kalıcı depolama için yerleşik medya yüklemelerini veya Files API’yi kullanın.

Yerleşik medya yüklemeleri (CMS medya özelliği)

Çoğu uygulama Files API’yi doğrudan kullanmaz — medya, yerleşik bir CMS özelliğidir. Uygulama şablonu @/hooks/useContent içinde iki yükleme hook’u ile gelir ve AI bunları arayüzünüze bağlar. Ne istediğinizi tarif edersiniz (“ürünlerimde bir görsel alanı”, “iletişim formumda dosya yükleme”) ve Proyecta doğru olanı kullanır:

Hook	Kullanıldığı yer	Endpoint	Boyut sınırı
useAssetUpload()	Yönetici medya kitaplığı — yönetici panelindeki içerik düzenleyicisindeki varlık seçiciyi destekler	POST /v1/public/files	10 MB
useFormFileUpload()	Herkese açık form dosyaları — <FormBlock/> dosya alanındaki ziyaretçi yüklemeleri (makbuzlar, fotoğraflar)	POST /v1/public/uploads	5 MB

Her iki hook da içerik girişinde (yönetici) veya form gönderiminde (herkese açık) sakladığınız kalıcı bir herkese açık url döndürür. Bilmeniz gereken birkaç şey:

• Her iki sınır da plana göre değil, kod ile uygulanır — yönetici medyası için 10 MB, herkese açık form dosyaları için 5 MB.
• Kabul edilen tipler yalnızca görsellerdir (SVG hariç) ve PDF. SVG güvenlik nedeniyle reddedilir; büyük görseller yüklemeden önce otomatik olarak küçültülür.
• Bunları doğrudan çağırmazsınız — AI bunları bağlar. Daha düşük seviyeli veya özel dosya işleme için aşağıdaki Files API’ye başvurun.

Files API

Yayımlanmış her Proyecta uygulaması dosya depolayıp sunabilir. Uygulamanızın sayfalarından bu tek bir çağrıdır — çok adımlı imzalı yükleme dansı sizin için halledilir:

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

Özel dosyalar. Bir dosyayı herkese açık bucket dışında, kalıcı URL’si olmadan saklamak için visibility: 'private' geçirin. Onu bunun yerine kısa ömürlü bir bağlantıyla geri okuyun:

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

Tahmin edilebilir olmaması gereken her şey için özel dosya + imzalı URL kullanın — müşteri yüklemeleri, kimlik belgeleri, ücretli indirmeler.

Dosyalar uygulamama nasıl yüklenir?

Dosya yüklemeleri AI builder aracılığıyla gerçekleştirilir. AI’dan yükleme akışını sizin için oluşturmasını isteyin:

• "Kullanıcıların bir profil fotoğrafı yüklemesine ve bunu Proyecta Files'ta depolamasına izin ver"
• "Oturum açmış kullanıcıların fotoğraf yükleyip görüntüleyebileceği bir görsel galerisi ekle"
• "Siparişlere PDF fatura ekleyebilmemi sağla"

AI, uygulamanızın koduna yüklemeyi bağlar ve döndürülen herkese açık URL’yi referans alır.

SSS

Dosya URL’leri herkese açık mı?

Evet. Files API tarafından döndürülen her dosya kalıcı bir herkese açık URL’ye sahiptir. Açığa çıkmasını istemediğiniz hiçbir şeyi yüklemeyin.

Bir dosya ne kadar büyük olabilir?

Dosya boyutları plana göre değil, kod ile sınırlandırılmıştır: yönetici medya kitaplığı yüklemeleri (useAssetUpload) için 10 MB, herkese açık form dosyası yüklemeleri (useFormFileUpload) için 5 MB ve sohbet ekleri için 10 MB. Yerleşik medya yüklemeleri yalnızca görselleri (SVG hariç) ve PDF’yi kabul eder.

URL üzerinden görselleri yeniden boyutlandırabilir veya kırpabilir miyim?

Anında görsel dönüşümleri (yeniden boyutlandırma, kırpma, format dönüştürme) yol haritasında yer almaktadır.

Yakında

• URL parametreleri aracılığıyla görsel dönüşümleri (yeniden boyutlandırma, kırpma, format dönüştürme)
• Klasör organizasyonu — depolanan dosyalar için klasör yolları oluşturun ve yönetin