Dokumentasi API
Integrasikan Vectorgram ke dalam aplikasi Anda. Satu endpoint untuk mengirim, satu untuk polling, satu untuk mengunduh — job memang dirancang asinkron. URL dasar https://api.vectorgram.ai, autentikasinya Authorization: Bearer <api_key>. Kuncinya berbentuk vectorgram_sk_live_… — prefiksnya sengaja ditulis lengkap, sehingga kunci yang ditemukan di sebuah .env yang lama dapat dikenali tanpa perlu dicoba.
Akun baru mendapat 25 konversi API gratis selama 30 hari — kualitas penuh, tanpa watermark. Setelah itu API memerlukan paket yang mencakupnya (Pro ke atas), dan panggilan dihitung dari jatah bulanan paket tersebut. Tidak ada overage: melewati jatah, panggilan dijawab 402 beserta tanggal resetnya. GET /v1/account menampilkan kedua jatah beserta sisa masing-masing.
Mulai cepat
1 — Dapatkan kunci API Anda
Memuat…
2 — Kirim sebuah gambar
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"Responsnya adalah 202 Accepted dengan job yang masih dalam antrean — konversi belum terjadi. Mengirim permintaan yang sama dua kali dengan satu Idempotency-Key akan mengembalikan job pertama, bukan membuat yang kedua; mengubah file atau pengaturan dengan kunci yang sudah terpakai berarti 409.
3 — Polling, atau terima 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 berjalan melalui queued → processing → completed | failed | canceled | expired. Saat masih dalam antrean, Anda menerima queue_position yang nyata, bukan hitungan mundur buatan; progress selama pemrosesan diinterpolasi dari estimasi ukuran dan dibatasi maksimal 95% sampai file ada. Gambar besar bisa memakan waktu beberapa menit — lakukan polling dengan interval yang wajar, atau lebih baik lagi, daftarkan webhook.
4 — Unduh
{
"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 hanya muncul setelah hasilnya ada, memerlukan bearer token yang sama, dan meng-stream file sebagai attachment. Dengan retention=none file dihapus saat disajikan — unduh sekali saja.
Parameter konversi
Semua field berupa multipart form data pada POST /v1/vectorize. Empat field yang ditandai manual adalah kontrol penelusuran: tersedia pada Pro, Studio, Agency dan Enterprise. Pada Free dan Lite, field ini diterima lalu diganti dengan nilai bawaan, bukan ditolak, sehingga klien yang selalu mengirimnya tetap bisa berkonversi — yang didapat hanyalah hasil otomatis.
Wajib. Gambar yang akan dikonversi. Dikenali dari byte-nya, bukan dari nama file-nya.
Jenis gambar yang dikirim. Nilai bawaannya auto, yang menyerahkan klasifikasi ke mesin.
Opsional, dan svg adalah satu-satunya nilainya. SVG adalah yang ditulis mesin dan tidak ada apa pun yang mengonversinya menjadi format lain — EPS, PNG, PDF, DXF dan AI ditolak dengan 400 unsupported_output_format, bukan dimasukkan ke antrean untuk gagal.
Berapa lama hasil disimpan. Bawaan 24h; none menghapusnya setelah unduhan pertama. Dibatasi ke maksimum paket Anda, bukan ditolak — Free tidak bisa menyimpan hasil selama 10 hari hanya dengan memintanya.
Kunci pengelompokan milik Anda sendiri, dikembalikan pada job dan bisa dipakai sebagai filter. Kirim satu permintaan per gambar. Konversi batch mulai berlaku di Pro (30 file, 50 di Studio, 100 di Agency); di bawahnya grup hanya menampung satu file dan file kedua dijawab dengan 400 batch_limit_exceeded.
Nama folder tempat file batch akan tersimpan di dasbor. Opsional dan memerlukan batch_id (jika tidak, 400 invalid_folder_name); dibatasi seperti batch_id — 128 karakter, tanpa karakter kontrol. File pertama yang diterima menamai folder; file batch berikutnya tidak mengganti namanya. Jika tidak diisi, folder diberi stempel tanggal pembuatannya.
Seberapa banyak gambar yang bertahan melalui penggabungan region. Bawaan high — langkah paling longgar yang dimiliki mesin sejak 1.3.0. Nilai slider 1–100 diterima dan dikelompokkan ke tingkat terdekat.
Penanganan gradien. Bawaan smooth; stepped dan auto membiarkan isian datar milik mesin.
Pembulatan sudut. Bawaan strong — sudut yang sungguhan tetap tajam; hanya bagian yang tanpa sengaja dibulatkan mesin vektorisasi yang ikut membulat. Nilai slider 0–100 diterima dan dikelompokkan ke tingkat terdekat.
Apa yang digambar mesin. Bawaan fill — setiap bentuk berupa garis luar berisian. centerline menggambar satu goresan terbuka di sepanjang tengah setiap garis (fill="none", dengan warna dan tebal goresan), yang diikuti oleh plotter, mesin gravir laser, CNC router dan mesin pemotong vinil: satu lintasan per garis, bukan dua garis luar di sekelilingnya. Bagian yang terlalu tebal untuk menjadi garis tetap berupa bentuk berisian. detail, gradients dan smoothing tidak berlaku dan diabaikan. Nilai yang tidak dikenal dijawab dengan 400.
Penutupan jahitan, tersedia di semua paket. Bawaan true — setiap isian menjorok 0,75 px ke bawah tetangganya, sehingga tidak ada garis terang tipis yang tampak di antara dua warna. false memberikan pembagian yang persis, tempat bentuk-bentuk bertemu dari tepi ke tepi tanpa tumpang-tindih (untuk mengedit geometri). Tidak ada bentuk yang berpindah dalam kedua kasus. Diabaikan dengan centerline.
Endpoint
Referensi yang dihasilkan — setiap field, setiap bentuk respons — adalah Swagger UI yang disajikan layanan di /docs/swagger, dengan dokumen OpenAPI di /v3/api-docs.
Webhook
Karena job berjalan secara asinkron — beberapa menit untuk file besar — berlanggananlah webhook alih-alih melakukan polling. Daftarkan endpoint dengan POST /v1/webhooks; secret penandatanganan dikembalikan hanya sekali, saat pembuatan, dan tidak pernah lagi setelahnya.
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" }
}Verifikasi signature dengan menghitung HMAC-SHA256 dari body permintaan mentah memakai secret endpoint Anda dan membandingkannya dalam waktu konstan — perlakukan ketidakcocokan sebagai permintaan yang tidak terautentikasi. Pengiriman berlangsung minimal sekali: respons non-2xx dicoba ulang tiga kali dengan exponential backoff, jadi buat handler Anda idempoten terhadap id. Endpoint harus ter-resolve ke alamat publik; ini diperiksa ulang saat pengiriman, bukan hanya saat pendaftaran.
Error
Kegagalan berbentuk JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Baca code, bukan pesannya — pesan bisa berubah sewaktu-waktu.