파일 및 미디어

앱에서 파일과 미디어를 저장하세요. 모든 파일에는 영구적인 공개 URL이 부여됩니다.

Proyecta의 미디어는 두 가지 레이어로 구성됩니다. 대부분의 앱은 기본 제공 CMS 미디어 기능을 사용합니다 — AI가 관리자 패널과 폼에 자동으로 연결해 주는 이미지 및 파일 업로드입니다. 그 아래에는 필요할 때 직접 제어할 수 있는 하위 수준 Files API가 있습니다. 두 방식 모두 CDN 기반의 오브젝트 스토리지에 저장되며, 영구적인 공개 URL을 반환합니다.

채팅 첨부 파일

채팅 입력창은 이미지를 직접 받을 수 있습니다 — 스크린샷을 붙여넣거나 이미지 파일을 입력창에 드래그하면 됩니다. 지원 형식: PNG, JPEG, WebP, GIF, AVIF. 최대 크기: 이미지당 10 MB.

채팅 첨부 파일은 메시지의 일부로 처리되며, 파일 라이브러리에는 저장되지 않습니다. 영구 저장이 필요하다면 기본 제공 미디어 업로드 또는 Files API를 사용하세요.

기본 제공 미디어 업로드 (CMS 미디어 기능)

대부분의 앱은 Files API를 직접 사용하지 않습니다 — 미디어는 기본 제공 CMS 기능입니다. 앱 템플릿에는 @/hooks/useContent에 두 가지 업로드 훅이 포함되어 있으며, AI가 이를 UI에 연결해 줍니다. 원하는 것을 설명하면 (“내 상품에 이미지 필드 추가”, “문의 폼에 파일 업로드 추가”) Proyecta가 적절한 훅을 사용합니다:

훅	사용 위치	엔드포인트	크기 제한
useAssetUpload()	관리자 미디어 라이브러리 — 관리자 패널 콘텐츠 편집기의 에셋 선택기에서 사용	POST /v1/public/files	10 MB
useFormFileUpload()	공개 폼 파일 — <FormBlock/> 파일 필드에서 방문자가 업로드하는 파일 (영수증, 사진 등)	POST /v1/public/uploads	5 MB

두 훅 모두 콘텐츠 항목(관리자) 또는 폼 제출(공개)에 저장할 영구 공개 url을 반환합니다. 알아두어야 할 사항:

• 두 크기 제한은 플랜이 아닌 코드로 적용됩니다 — 관리자 미디어는 10 MB, 공개 폼 파일은 5 MB.
• 허용 형식은 이미지(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' });

추측으로 접근되면 안 되는 것 — 고객 업로드 파일, 신분증 서류, 유료 다운로드 — 에는 비공개 저장과 서명 URL을 사용하세요.

앱에서 파일을 어떻게 업로드하나요?

파일 업로드는 AI 빌더를 통해 처리됩니다. AI에게 업로드 흐름을 만들어 달라고 요청하세요:

• "사용자가 프로필 사진을 업로드하고 Proyecta Files에 저장할 수 있게 해줘"
• "로그인한 사용자가 사진을 업로드하고 볼 수 있는 이미지 갤러리를 추가해줘"
• "주문에 PDF 청구서를 첨부할 수 있게 해줘"

AI가 앱 코드에 업로드 기능을 연결하고, 반환된 공개 URL을 참조합니다.

자주 묻는 질문

파일 URL은 공개인가요?

네. Files API가 반환하는 모든 파일에는 영구 공개 URL이 있습니다. 외부에 노출되어도 괜찮은 파일만 업로드하세요.

파일 크기 제한은 얼마인가요?

파일 크기는 플랜이 아닌 코드로 제한됩니다: 관리자 미디어 라이브러리 업로드(useAssetUpload)는 10 MB, 공개 폼 파일 업로드(useFormFileUpload)는 5 MB, 채팅 첨부 파일은 10 MB입니다. 기본 제공 미디어 업로드는 이미지(SVG 제외)와 PDF만 허용합니다.

URL에서 이미지를 리사이즈하거나 크롭할 수 있나요?

URL 파라미터를 통한 실시간 이미지 변환(리사이즈, 크롭, 포맷 변환)은 로드맵에 포함되어 있습니다.

출시 예정

• URL 파라미터를 통한 이미지 변환 (리사이즈, 크롭, 포맷 변환)
• 폴더 구조 관리 — 저장된 파일의 폴더 경로 생성 및 관리