SDK 설치하기
TypeScript/JavaScript(Node.js 및 브라우저) 및 Python용 공식 완전 타입 지정 SDK입니다. API를 직접 호출하고 싶으신 경우를 위해, 아래의 각 단계에는 이에 상응하는 cURL 요청도 함께 표시되어 있습니다.
bash
npm install @uploadcenter/sdk-jstypescript
import { createClient } from "@uploadcenter/sdk-js";
const client = createClient({
baseUrl: "https://api.uploadscenter.com",
token: process.env.UPLOADCENTER_API_KEY, // an API key from your project settings
});모든 메서드는 UploadCenter의 OpenAPI 스키마를 기반으로 생성되므로, 자동 완성 기능은 전체 API 범위를 아우릅니다 — npm에서 JS 패키지 보기 또는 PyPI에 있는 Python 패키지.
1
계정 만들기
가입 시 작업 공간(조직)이 자동으로 생성됩니다.
2
프로젝트와 API 키 생성하기
대시보드에서 프로젝트를 생성한 다음, 해당 프로젝트에 적용되는 API 키를 생성하세요. 전체 키는 한 번만 표시되므로 즉시 복사해 두세요.
3
업로드에 사전 서명하기
API에 사전 서명된 URL을 요청하세요. 파일은 사용자의 백엔드를 절대 통과하지 않습니다.
bash
curl -X POST https://api.uploadscenter.com/v1/uploads/presign \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"project_id": "project_...",
"filename": "photo.jpg",
"size_bytes": 128000,
"mime_type": "image/jpeg",
"visibility": "private"
}'4
파일 업로드하기
파일을 반환된 upload_url에 직접 올려주세요. 이렇게 해야 파일 크기에 상관없이 업로드 속도가 빨라집니다.
bash
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--data-binary @photo.jpg5
업로드 확인
이것이 바로 바이러스 백신 검사 및 처리를 시작하는 계기입니다. 검사가 완료될 때까지는 파일이 ‘준비됨’ 상태로 표시되지 않습니다.
bash
curl -X POST https://api.uploadscenter.com/v1/uploads/complete \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"file_id": "file_..."}'파일 내용 다시 읽기 — GET /v1/files/{file_id}/url — 비공개 파일의 경우 항상 유효한 API 키나 세션이 필요합니다. 공개 파일의 경우 작동 방식이 다릅니다. — 아래 내용을 참조하십시오.
공개 URL
공개(public)로 설정하여 업로드하면, 파일이 준비되는 즉시 해당 파일의 URL 필드에는 영구적이고 인증이 필요 없는 링크가 생성됩니다. 이 링크는 직접 삽입해도 안전하며, 엣지 서버에 캐시되어 유효기간이 없습니다.
json
GET /v1/files/{file_id}
{
"id": "file_...",
"visibility": "public",
"status": "ready",
"url": "https://cdn.uploadscenter.com/o/…/photo.jpg"
}비공개 파일(기본 설정)에는 URL 필드가 없습니다. 대신 GET /v1/files/{id}/url을 호출하면, 제한된 기간 동안 유효한 새로 생성된 서명된 링크가 반환됩니다.
이벤트에 반응하기
프로젝트 설정에서 웹훅을 추가하면 파일 업로드, 처리 및 할당량 관련 이벤트에 대한 알림을 받을 수 있습니다. 모든 전송 데이터에는 서명이 포함되어 있으므로, 페이로드를 신뢰하기 전에 반드시 서명을 확인하십시오.
http
POST <your webhook URL>
Content-Type: application/json
X-Signature: sha256=<hex-encoded HMAC-SHA256>
X-Timestamp: <unix timestamp, seconds>
{"event":"file.processed","created_at":"2026-01-01T12:00:00Z","data":{"id":"file_...","project_id":"project_...","status":"ready", ...}}행사: file.uploaded, file.processed, file.failed, file.quarantined, file.flagged, storage.limit_reached. 전달이 실패로 처리되기 전까지 최대 3회(30초, 2분, 10분 간격으로)의 전달 시도가 이루어집니다.
typescript
import crypto from "node:crypto";
// Sign over "${timestamp}.${rawBody}" — rawBody must be the exact bytes
// received, not a re-serialized JSON.stringify(JSON.parse(rawBody)).
function verifyWebhook(rawBody: string, timestamp: string, signatureHeader: string, secret: string): boolean {
const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
const provided = signatureHeader.replace(/^sha256=/, "");
return crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(provided, "hex"));
}
// signatureHeader = req.headers["x-signature"]
// timestamp = req.headers["x-timestamp"]이미지를 실시간으로 변환
쿼리 매개변수를 사용하여 크기 조정, 자르기, 형식 변환을 수행할 수 있습니다. 결과는 첫 번째 요청 후 캐시되므로, 이후 요청 시마다 다시 계산되지 않습니다.
http
GET /v1/files/{file_id}/transform?w=480&h=320&format=auto&fit=cover
# fit: "cover" (crop to fill) or "inside" (contain)
# format: auto (default) | webp | jpeg | png
# quality: auto (default) | 1-100
#
# format=auto picks WebP or JPEG based on the request's Accept header —
# no more branching client-side for older browsers. quality=auto applies
# a sensible per-format default (80 for WebP, 82 for JPEG). Pass explicit
# values any time you want full control instead.이미지에 워터마크를 추가하세요
프로젝트의 로고를 어떤 변환 위에든 오버레이할 수 있습니다. 위치, 불투명도, 크기는 모두 자유롭게 설정할 수 있으며, 결과물은 다른 변환과 마찬가지로 캐시됩니다.
http
PUT /v1/projects/{project_id}/watermark
{"file_id": "file_..."} # any image already uploaded to the project
GET /v1/files/{file_id}/transform?w=1200&watermark=true&gravity=south_east&opacity=60&overlay_scale=0.2
# gravity: north_west | north_east | south_west | south_east | center
# opacity: 1-100 (default 60)
# overlay_scale: 0.05-1.0 (default 0.2, fraction of the output image's width)사용자 지정 도메인
DNS를 통해 소유권이 확인되면, 공유 CDN 대신 자체 도메인에서 공개 파일을 제공하십시오.
http
POST /v1/domains
{"project_id": "project_...", "hostname": "cdn.yourapp.com"}
# Add the returned TXT record at your DNS provider, then:
POST /v1/domains/{domain_id}/verify
# Once verified, point cdn.yourapp.com at UploadCenter (A/CNAME — shown in
# the dashboard) and a TLS certificate is issued automatically. From then
# on, every public file's url uses your domain instead of the shared CDN.콘텐츠 검토
업로드된 이미지는 노골적인 콘텐츠가 있는지 자동으로 검토됩니다. 이는 단순한 탐지 과정일 뿐이며, 사용자를 대신해 콘텐츠가 차단되거나 삭제되는 일은 절대 없습니다.
json
GET /v1/files/{file_id}
{
"id": "file_...",
"status": "ready",
"moderation_status": "flagged", // null (not evaluated) | "clean" | "flagged" | "error"
"moderation_score": 0.87
}표시된 파일은 업로드된 그대로 유지됩니다. ‘표시됨’이 해당 제품에서 어떤 의미를 가지는지는 앱에서 결정합니다. 유료 요금제에서 이용 가능하며, 자세한 내용은 기능 페이지를 참조하세요.
동영상 썸네일 및 파생 파일
동영상을 업로드할 때마다 자동으로 JPEG 썸네일이 생성되며, 용량이 작은 동영상의 경우 720p MP4로 변환됩니다. 각 버전의 고유 URL은 별도의 서명 절차 없이 바로 사용할 수 있습니다.
json
GET /v1/files/{file_id}/variants
[
{ "variant": "thumbnail", "format": "jpg", "width": 640, "height": 360, "url": "https://…" },
{ "variant": "720p", "format": "mp4", "width": 1280, "height": 720, "url": "https://…" }
]AI 이미지 및 동영상 생성
이미지를 생성, 편집, 배경 제거, 화질 향상하거나 다양한 변형 이미지를 만들 수 있으며, 텍스트나 기존 이미지를 바탕으로 동영상을 생성할 수 있습니다. 모든 호출은 비동기 방식으로 이루어집니다. 생성 ID가 포함된 202 응답을 받은 후, 해당 ID를 폴링하거나 ai.generation.completed / ai.generation.failed 웹훅을 수신 대기하면 됩니다.
typescript
const generation = await client.ai.generateImageEndpointV1AiImagesGeneratePost({
project_id: projectId,
prompt: "a minimalist logo of a fox, flat vector style",
use_brand_kit: true, // pulls in this org's brand kit colors/fonts
});
// 202 Accepted — poll until it settles (or listen for the webhook below).
const result = await client.ai.getGenerationEndpointV1AiGenerationsGenerationIdGet(
generation.id,
projectId,
);
// result.file_ids — the new file(s), same shape as anything you upload그 결과, 직접 업로드하는 파일과 똑같이 고유한 공개 설정, 전달 방식 및 수명 주기를 가진 일반 파일(생성이 완료되면 ‘file_ids’)이 생성됩니다.
의미 기반 검색
파일 이름 대신 평이한 언어로 파일을 검색하세요 — 키워드 일치가 아닌 AI 캡션과 임베딩 기술을 기반으로 합니다.
http
GET /v1/ai/search?project_id={project_id}&q=cat+sitting+on+a+couch&limit=20
# Ranks files by AI caption similarity (files.ai_caption, produced by the
# analyze-image capability) — not full-text search over filenames.
# GET /v1/files/{file_id}/similar finds files with a similar caption.신뢰성, 솔직히 말해서
UploadCenter는 설립된 지 얼마 되지 않았고 활발히 개발 중인 플랫폼입니다. 수년에 걸친 가동 시간 기록을 제시할 수는 없으며, 임의로 수치를 만들어내지도 않을 것입니다. 현재 구축된 시스템은 다음과 같습니다: 모든 파일은 제공되기 전에 반드시 바이러스 검사를 거치며, 업로드 처리는 원자적으로 수행됩니다(한 단계에서 오류가 발생하더라도 처리 과정이 중단되지 않습니다). 또한 파일 전송은 Cloudflare 네트워크를 통해 이루어집니다. 아직 공식적인 SLA(서비스 수준 계약)는 마련되어 있지 않습니다. 계약상 보장이 필요한 사용 사례라면, 저희에게 연락해 주시면 현실적으로 가능한 방안에 대해 논의해 드리겠습니다.