파일 & 미디어

앱 코드에서 파일을 업로드하고 관리하세요. 모든 파일에는 영구적인 공개 URL이 부여됩니다.

Proyecta는 앱 코드에서 프로그래밍 방식으로 파일을 관리할 수 있도록 SDK를 통해 Files API를 제공합니다.

채팅 첨부 파일

채팅 입력란에 이미지를 직접 붙여넣거나 드래그해서 올릴 수 있습니다. 지원 형식: PNG, JPEG, WebP, GIF, AVIF. 최대 크기: 이미지 당 10 MB.

채팅 첨부 파일은 메시지의 일부이며 파일 라이브러리에 저장되지 않습니다. 영구 저장이 필요하다면 SDK를 사용하세요.

Files API (SDK)

모든 Proyecta 앱은 Proyecta SDK를 통해 파일 저장 API에 접근할 수 있습니다. SDK는 파일 목록 조회, 가져오기, 업로드를 지원합니다. 업로드된 파일에는 앱에서 참조할 수 있는 영구 공개 URL이 부여됩니다.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

// List files (supports limit and starting_after for pagination)
const files = await proyecta.files.list();

// Fetch a single file by ID
const file = await proyecta.files.get('1234567890123456789');
console.log(file.url); // permanent public URL

// Upload a file (two-step)
// Step 1: create a placeholder and get a signed upload URL
const { id: fileId, upload_url } = await proyecta.files.create({
    filename: 'avatar.png',
    mime_type: 'image/png',
});

// Step 2: PUT the file bytes directly to the signed URL
await fetch(upload_url, {
    method: 'PUT',
    body: fileBytes,
    headers: { 'Content-Type': 'image/png' },
});

// Step 3: finalize to get the permanent file record
const uploaded = await proyecta.files.finalize({ fileId });
console.log(uploaded.url); // permanent public URL, now populated

각 파일은 다음 필드를 포함합니다:

필드	설명
id	고유 식별자 (숫자형 snowflake 문자열)
url	영구 공개 URL (finalize 단계 이후 채워짐)
filename	업로드 시 원본 파일명
mime_type	image/jpeg, application/pdf 등
size	파일 크기 (바이트)
path	선택적 폴더 경로 (예: /images/blog)
content_hash	파일 내용의 SHA-256 해시
metadata	임의의 키/값 메타데이터
created	ISO 8601 형식의 생성 타임스탬프
updated	ISO 8601 형식의 마지막 수정 타임스탬프

앱에 파일 업로드 기능을 추가하려면?

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

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

AI는 SDK의 2단계 업로드 API를 사용해 앱 코드에 업로드 기능을 연결하고, 반환된 공개 URL을 참조합니다. files.create() / files.finalize()를 직접 앱 코드에서 호출할 수도 있습니다.

FAQ

파일 URL은 공개되나요?

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

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

파일당 크기 제한은 플랜에 따라 다릅니다. 채팅 첨부 파일은 이미지 당 10 MB로 제한됩니다.

URL에서 이미지 크기 조정이나 크롭이 가능한가요?

온디맨드 이미지 변환(크기 조정, 크롭, 포맷 변환)은 로드맵에 포함되어 있습니다.

출시 예정

• URL 파라미터를 통한 이미지 변환 (크기 조정, 크롭, 포맷 변환)
• 폴더 구성 — 패널에서 폴더 경로 생성 및 관리
• 파일 행에서 “채팅에 추가” — 라이브러리 에셋을 AI 대화에 바로 드롭