API 문서
애플리케이션에 Vectorgram을 연동합니다. 제출용 엔드포인트 하나, 폴링용 하나, 다운로드용 하나 — 작업은 설계상 비동기입니다. 베이스 URL https://api.vectorgram.ai, 인증은 Authorization: Bearer <api_key>입니다. 키는 vectorgram_sk_live_… 형태이며, 접두사를 일부러 온전히 써 두었으므로 오래된 .env 에서 발견된 키도 대입해 보지 않고 식별할 수 있습니다.
새 계정은 30일간 API 변환 25회를 무료로 받습니다 — 전체 품질, 워터마크 없음. 이후에는 API가 포함된 플랜(Pro 이상)이 필요하고 호출은 그 플랜의 월 할당량에서 차감됩니다. 초과 과금은 없습니다. 할당량을 넘기면 호출의 응답은 402이며 초기화일이 함께 돌아옵니다. GET /v1/account 는 두 할당량과 각각의 남은 양을 모두 알려줍니다.
빠른 시작
1 — API 키 발급
불러오는 중…
2 — 이미지 제출
curl -X POST https://api.vectorgram.ai/v1/vectorize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 8f1b0c2e-0a1d-4f77-9c3a-2b6e5d4c1a90" \
-F "file=@image.png" \
-F "image_type=clipart" \
-F "detail=high" \
-F "gradients=smooth" \
-F "smoothing=strong" \
-F "retention=24h"응답은 202 Accepted이며 작업이 대기열에 들어갑니다 — 아직 변환은 일어나지 않았습니다. 동일한 Idempotency-Key 로 같은 요청을 두 번 보내면 두 번째 작업을 만드는 대신 첫 번째 작업이 반환됩니다. 이미 사용한 키로 파일이나 설정을 바꾸면 409입니다.
3 — 폴링 또는 웹훅 수신
GET /v1/jobs/job_abc123
{
"id": "job_abc123",
"status": "queued",
"progress": 0,
"queue_position": 3,
"mode": "logo",
"retention": "24h",
"megapixels": 2.1,
"created_at": "2026-08-03T10:30:00Z"
}status는 다음 순서로 진행됩니다: queued → processing → completed | failed | canceled | expired 대기 중에는 지어낸 카운트다운이 아니라 실제 queue_position가 돌아오고, 처리 중의 progress는 크기 추정치에서 보간되며 파일이 실제로 존재할 때까지 95%에서 머뭅니다. 큰 이미지는 몇 분이 걸릴 수 있습니다 — 상식적인 간격으로 폴링하거나, 더 좋게는 웹훅을 등록하세요.
4 — 다운로드
{
"id": "job_abc123",
"status": "completed",
"progress": 100,
"download_url": "https://api.vectorgram.ai/v1/jobs/job_abc123/download",
"completed_at": "2026-08-03T10:30:04Z",
"expires_at": "2026-08-04T10:30:04Z"
}download_url는 결과가 존재할 때만 나타나고, 같은 베어러 토큰이 필요하며, 파일을 첨부 형태로 스트리밍합니다. retention=none 로 설정하면 파일은 전달되면서 삭제됩니다 — 다운로드는 한 번만.
변환 파라미터
모든 필드는 POST /v1/vectorize 로 전송하는 multipart form data입니다. 수동 표시가 붙은 네 항목이 트레이스 컨트롤입니다. Pro, Studio, Agency, Enterprise에서 사용할 수 있습니다. Free와 Lite에서는 거절되지 않고 받아들여진 뒤 기본값으로 대체되므로, 항상 이들을 보내는 클라이언트도 변환에 성공합니다 — 자동 결과를 받을 뿐입니다.
필수. 변환할 이미지입니다. 파일명이 아니라 바이트에서 판별합니다.
이 이미지의 종류입니다. 기본값은 auto이며, 엔진이 분류합니다.
선택적이며 svg가 유일한 값입니다. 엔진이 쓰는 것은 SVG이고 어디에서도 이를 다른 형식으로 바꾸지 않습니다 — EPS, PNG, PDF, DXF, AI는 실패하려고 대기열에 들어가는 대신 400 unsupported_output_format으로 거절됩니다.
결과를 얼마나 보관하는지입니다. 기본값은 24h, none은 첫 다운로드 후 삭제합니다. 플랜 최대치로 조정되며 거절되지 않습니다 — Free가 10일을 요청해도 10일간 보관되지는 않습니다.
직접 정하는 그룹핑 키로, 작업에 그대로 되돌아오며 필터로 쓸 수 있습니다. 이미지당 요청 하나를 제출합니다. 일괄 변환은 Pro부터입니다(30개 파일, Studio 50개, Agency 100개). 그 아래에서는 그룹이 파일 하나만 담고 두 번째는 400 batch_limit_exceeded로 응답합니다.
일괄 파일이 대시보드에 담길 폴더의 이름입니다. 선택 사항이며 batch_id가 필요합니다(없으면 400 invalid_folder_name). batch_id와 같은 제한 — 128자, 제어 문자 불가. 처음 들어온 파일이 폴더 이름을 정하고, 이후 파일이 이름을 바꾸지는 않습니다. 생략하면 폴더는 생성일로 이름 지어집니다.
영역 병합에서 이미지가 얼마나 남는지입니다. 기본값은 high — 1.3.0부터 엔진의 가장 느슨한 단계입니다. 1–100 슬라이더 값도 받아들여 구간으로 분류합니다.
그라디언트 처리입니다. 기본값은 smooth이며, stepped와 auto는 엔진의 플랫 채우기를 그대로 둡니다.
코너 라운딩입니다. 기본값은 strong — 진짜 코너는 날카로운 채로 남고, 트레이서가 실수로 둥글게 만든 부분만 돌아옵니다. 0–100 슬라이더 값도 받아들여 구간으로 분류합니다.
엔진이 그리는 대상입니다. 기본값은 fill — 모든 도형이 채워진 외곽선입니다. centerline은 각 선의 중심을 따라 열린 스트로크 하나를 그립니다(fill="none", 스트로크 색과 두께 포함). 플로터, 레이저 조각기, CNC 라우터, 비닐 커팅기가 따라가는 방식으로, 선 주위 두 겹의 외곽선 대신 선당 한 번의 패스입니다. 선으로 보기엔 너무 두꺼운 부분은 채워진 도형으로 남습니다. detail, gradients, smoothing은 적용되지 않고 무시됩니다. 알 수 없는 값은 400으로 응답합니다.
이음새 처리로, 모든 플랜에서 제공됩니다. 기본값은 true — 각 채우기가 이웃 아래로 0.75 px 겹쳐 두 색 사이에 가는 밝은 선이 보이지 않습니다. false는 정확한 분할을 반환하며 도형이 겹침 없이 모서리에서 맞닿습니다(지오메트리 편집용). 어느 쪽이든 도형이 움직이지는 않습니다. centerline에서는 무시됩니다.
엔드포인트
모든 필드와 모든 응답 형태가 담긴 생성 레퍼런스는 서비스가 제공하는 Swagger UI입니다 — 주소는 /docs/swagger이고, OpenAPI 문서는 /v3/api-docs에 있습니다.
웹훅
작업은 비동기로 실행되고 큰 파일은 몇 분이 걸리므로, 폴링 대신 웹훅을 구독하세요. 엔드포인트는 POST /v1/webhooks 로 등록합니다. 서명 시크릿은 생성 시점에 한 번 반환되고 다시는 제공되지 않습니다.
POST https://your-app.example/hooks/vectorgram
X-Vectorgram-Event: processing.completed
X-Vectorgram-Signature: sha256=<hmac of the raw body, hex>
{
"id": "evt_9f2c…",
"event": "processing.completed",
"created_at": "2026-08-03T10:30:04Z",
"data": { "job_id": "job_abc123", "status": "completed" }
}서명 검증은 엔드포인트 시크릿으로 원문 요청 바디의 HMAC-SHA256을 계산해 상수 시간에 비교하는 방식입니다 — 불일치는 인증되지 않은 요청으로 취급하세요. 전달은 최소 한 번 보장이며, 2xx가 아닌 응답에는 지수 백오프로 세 번 재시도합니다. 핸들러는 다음 기준으로 멱등하게 만드세요 id. 엔드포인트는 공개 주소로 확인되어야 하며, 등록할 때뿐 아니라 전달할 때 다시 확인됩니다.
오류
실패 응답은 JSON입니다: { "error": { "code": "…", "message": "…", "details": { … } } }. 메시지가 아니라 code 를 읽으세요 — 메시지는 문구가 바뀝니다.