Tài liệu API
Tích hợp Vectorgram vào ứng dụng của bạn. Một endpoint để gửi, một để thăm dò, một để tải xuống — job vốn bất đồng bộ theo thiết kế. URL cơ sở https://api.vectorgram.ai, xác thực là Authorization: Bearer <api_key>. Khóa trông như vectorgram_sk_live_… — tiền tố được viết thẳng chủ ý như vậy, để một khóa tìm thấy trong .env cũ có thể nhận ra mà không phải đem ra thử.
Tài khoản mới bắt đầu ở Trial với 5 lượt chuyển đổi miễn phí — chất lượng đầy đủ, không watermark — để dùng trong trình duyệt hoặc qua API, chung một bộ đếm. Các lượt này chỉ cấp một lần và không gia hạn. Sau đó API cần gói có gồm nó (Pro trở lên), và lệnh gọi trừ vào hạn mức tháng của gói ấy. Không có phụ thu vượt hạn mức: vượt hạn mức, lệnh gọi trả lời 402 kèm ngày reset. GET /v1/account báo cáo mọi hạn mức — kể cả bản dùng thử — và phần còn lại của từng thứ.
Bắt đầu nhanh
1 — Lấy khóa API của bạn
Đang tải…
2 — Gửi một ảnh
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"Phản hồi là 202 Accepted kèm một job trong hàng đợi — chuyển đổi vẫn chưa diễn ra. Gửi cùng một yêu cầu hai lần với một Idempotency-Key trả về job đầu tiên thay vì tạo job thứ hai; đổi tệp hoặc thiết lập dưới một khóa đã dùng thì là 409.
3 — Thăm dò, hoặc nhận webhook
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 đi qua queued → processing → completed | failed | canceled | expired. Khi đang chờ bạn nhận đúng queue_position thay vì một đếm ngược bịa; progress trong lúc xử lý được nội suy từ ước lượng kích thước và dừng ở 95% cho đến khi tệp tồn tại. Ảnh lớn có thể mất vài phút — thăm dò với khoảng hợp lý, hoặc tốt hơn là đăng ký webhook.
4 — Tải xuống
{
"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 chỉ xuất hiện khi đã có kết quả, cần đúng bearer token ấy, và truyền tệp về dạng đính kèm. Với retention=none tệp bị xóa ngay khi được trao — hãy tải xuống một lần duy nhất.
Tham số chuyển đổi
Mọi trường là multipart form data trên POST /v1/vectorize. Bốn trường đánh dấu thủ công là các điều khiển truy vết: có trên Pro, Studio, Agency và Enterprise. Trên Trial và Lite chúng được nhận rồi thay bằng mặc định thay vì bị từ chối, nên một client luôn gửi chúng vẫn chuyển đổi được — chỉ là nhận kết quả tự động.
Bắt buộc. Ảnh cần chuyển đổi. Được nhận diện từ nội dung tệp, không phải từ tên tệp.
Đây là loại ảnh gì. Mặc định auto, để engine tự phân loại.
Tùy chọn, và svg là giá trị duy nhất. SVG là thứ engine ghi ra và không gì chuyển nó thành thứ khác — EPS, PNG, PDF, DXF và AI bị từ chối với 400 unsupported_output_format thay vì xếp hàng chờ lỗi.
Kết quả được giữ bao lâu. Mặc định 24h; none xóa nó sau lần tải xuống đầu tiên. Bị kẹp về mức tối đa của gói thay vì bị từ chối — Trial không thể giữ một kết quả 10 ngày chỉ bằng cách yêu cầu.
Khóa gom riêng của bạn, được phản hồi lại trên job và dùng được làm bộ lọc. Gửi một yêu cầu cho mỗi ảnh. Chuyển đổi hàng loạt bắt đầu từ Pro (30 tệp, 50 trên Studio, 100 trên Agency); dưới mức đó nhóm chỉ giữ được một tệp và tệp thứ hai nhận 400 batch_limit_exceeded.
Tên thư mục mà các tệp của lô sẽ nằm trong trên bảng điều khiển. Tùy chọn và cần batch_id (nếu không là 400 invalid_folder_name); giới hạn như batch_id — 128 ký tự, không ký tự điều khiển. Tệp đầu tiên được nhận sẽ đặt tên thư mục; các tệp sau của lô không đổi tên nó. Bỏ trống thì thư mục được đóng dấu theo ngày tạo.
Bao nhiêu phần ảnh sống sót qua bước gom vùng. Mặc định high — bước lỏng lẻo nhất mà engine có được kể từ 1.3.0. Một giá trị thanh trượt 1–100 được nhận và quy vào nhóm.
Xử lý gradient. Mặc định smooth; stepped và auto để phần tô phẳng của engine.
Làm tròn góc. Mặc định strong. Một giá trị thanh trượt 0–100 được nhận và quy vào nhóm.
Engine vẽ cái gì. Mặc định fill — mọi hình là một đường bao tô kín. centerline vẽ một nét hở chạy giữa mỗi đường kẻ (fill="none", kèm màu và độ rộng nét) — thứ mà plotter, máy khắc laser, máy CNC và máy cắt decal đi theo: một lần đi cho mỗi nét thay vì hai đường bao quanh nó. Phần quá dày để là một nét giữ nguyên dạng hình tô. detail, gradients và smoothing không áp dụng và bị bỏ qua. Giá trị lạ trả về 400.
Khép mép, trên mọi gói. Mặc định true — mỗi phần tô chạy 0,75 px xuống dưới phần liền kề, nên không khe sáng mảnh nào hiện giữa hai màu. false cho phân chia chính xác, nơi các hình khối khớp mép nhau không chồng lấn (để chỉnh hình học). Không hình nào di chuyển trong cả hai trường hợp. Bị bỏ qua với centerline.
Endpoint
Tài liệu tham khảo được sinh ra — mọi trường, mọi hình dạng phản hồi — là Swagger UI mà dịch vụ phục vụ tại /docs/swagger, kèm tài liệu OpenAPI tại /v3/api-docs.
Webhook
Vì job chạy bất đồng bộ — mấy phút với tệp lớn — hãy đăng ký webhook thay vì thăm dò. Đăng ký một endpoint bằng POST /v1/webhooks; khóa ký được trả về một lần duy nhất, lúc tạo, và không bao giờ lần nữa.
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" }
}Xác minh chữ ký bằng cách tính HMAC-SHA256 của phần thân yêu cầu thô với khóa bí mật endpoint của bạn và so sánh trong thời gian hằng số — coi sự không khớp là một yêu cầu chưa xác thực. Việc giao hàng ít nhất một lần: một phản hồi không phải 2xx được thử lại ba lần với backoff luỹ thừa, nên hãy làm handler idempotent trên id. Endpoint phải phân giải về một địa chỉ công khai; điều đó được kiểm tra lại lúc giao hàng, không chỉ lúc đăng ký.
Lỗi
Lỗi là JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Hãy đọc code, đừng đọc message — message hay được đổi chữ.