API Dokümantasyonu
Vectorgram'ı uygulamana entegre et. Göndermek için bir uç nokta, sorgulamak için bir uç nokta, indirmek için bir uç nokta — işler tasarımı gereği eşzamansızdır. Temel URL https://api.vectorgram.ai, kimlik doğrulama ise Authorization: Bearer <api_key>. Anahtarlar şuna benzer: vectorgram_sk_live_… — önek bilerek açıkça yazılır; böylece eski bir .env içinde bulunan anahtar, denenmeden ayırt edilebilir.
Yeni bir hesap 30 gün boyunca 25 ücretsiz API dönüştürme alır — tam kalite, filigran yok. Sonrasında API, bunu içeren bir plan ister (Pro ve üstü); çağrılar o planın aylık kotasından düşer. Fazla kullanım yoktur: kota bittiğinde çağrılar 402 ile yanıtlanır; yanıtta sıfırlanma tarihi de yer alır. GET /v1/account her iki kotayı ve her birinden kalanı bildirir.
Hızlı başlangıç
1 — API anahtarını al
Yükleniyor…
2 — Bir görsel gönder
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"Yanıt 202 Accepted ile gelir; iş kuyruğa alınmıştır, dönüştürme henüz gerçekleşmemiştir. Aynı isteği aynı Idempotency-Key ile iki kez göndermek ikinci bir iş üretmek yerine ilk işi döndürür; kullanılmış bir anahtar altında dosyayı ya da ayarları değiştirmek ise 409 ile sonuçlanır.
3 — Sorgula ya da webhook al
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 sırasıyla şöyle ilerler: queued → processing → completed | failed | canceled | expired. Kuyruktayken gerçek bir queue_position alırsın — uydurma bir geri sayım değil; progress işleme sırasında boyut tahmininden yola çıkılarak hesaplanır ve dosya var olana kadar %95'te sınırlanır. Büyük görseller dakikalar alabilir — makul bir aralıkla sorgula ya da daha iyisi bir webhook kaydet.
4 — İndir
{
"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 yalnızca bir sonuç var olduğunda görünür; aynı bearer token'ını ister ve dosyayı ek olarak akış hâlinde sunar. retention=none durumunda dosya sunulurken silinir — bir kez indir.
Dönüştürme parametreleri
Tüm alanlar POST /v1/vectorize uç noktasına multipart form data olarak gönderilir. manuel ile işaretli dört alan, izleme ayarlarıdır: Pro, Studio, Agency ve Enterprise'da bulunur. Free ve Lite'ta bunlar reddedilmek yerine kabul edilir ve varsayılanlarla değiştirilir; böylece bunları her zaman gönderen bir istemci yine de dönüştürür — sadece otomatik sonucu alır.
Zorunlu. Dönüştürülecek görsel. Dosya adından değil, baytlarından tanınır.
Bu görselin ne tür olduğu. Varsayılan auto; sınıflandırmayı motora bırakır.
İsteğe bağlıdır ve tek değer svg'dir. Motorun yazdığı şey SVG'dir ve hiçbir şey onu başka bir biçime dönüştürmez — EPS, PNG, PDF, DXF ve AI, başarısızlık için kuyruğa alınmak yerine 400 unsupported_output_format ile reddedilir.
Sonucun ne kadar süre saklanacağı. Varsayılan 24h; none, ilk indirmeden sonra siler. Reddedilmek yerine planının üst sınırına sabitlenir — Free, yalnızca isteyerek bir sonucu 10 gün tutamaz.
Kendi gruplama anahtarın; iş üzerinde geri yansıtılır ve filtre olarak kullanılabilir. Her görsel için bir istek gönder. Toplu dönüştürme Pro'da başlar (30 dosya, Studio'da 50, Agency'de 100); onun altındaki planlarda grup tek dosya tutar, ikinci dosya 400 batch_limit_exceeded yanıtı verir.
Toplu işin dosyalarının panelde duracağı klasörün adı. İsteğe bağlıdır ve batch_id gerektirir (yoksa 400 invalid_folder_name); batch_id gibi sınırlıdır — 128 karakter, kontrol karakteri yok. Kabul edilen ilk dosya klasörü adlandırır; toplu işin sonraki dosyaları onu yeniden adlandırmaz. Belirtilmezse klasör, oluşturulma tarihiyle damgalanır.
Bölge birleştirmesinden sonra görselin ne kadarının geride kaldığı. Varsayılan high — 1.3.0'dan beri motorun en gevşek adımı. 1–100 arası bir kaydırıcı değeri kabul edilir ve aralıklara ayrılır.
Geçişlerin (gradient) işlenmesi. Varsayılan smooth; stepped ve auto, motorun düz dolgularını olduğu gibi bırakır.
Köşe yuvarlatma. Varsayılan strong — gerçek köşeler keskin kalır; yalnızca vektörleştirme motorunun yanlışlıkla yuvarladıkları geri gelir. 0–100 arası bir kaydırıcı değeri kabul edilir ve aralıklara ayrılır.
Motorun ne çizdiği. Varsayılan fill — her şekil, dolgulu bir dış çizgidir. centerline, her çizginin orta çizgisi boyunca tek bir açık kontur çizer (fill="none", kontur rengi ve kalınlığıyla); bunu plotterlar, lazer gravür makineleri, CNC router'lar ve vinil kesme makineleri izler: çizginin çevresindeki iki kontur yerine çizgi başına bir geçiş. Çizgi olamayacak kadar kalın parçalar dolgulu şekil olarak kalır. detail, gradients ve smoothing uygulanmaz ve yok sayılır. Bilinmeyen bir değer 400 yanıtı verir.
Dikiş kapatma; tüm planlarda. Varsayılan true — her dolgu, komşusunun altına 0,75 px taşar; böylece iki renk arasında ince, açık bir çizgi görünmez. false, kesin bölümlemeyi verir: şekiller kenar kenara, örtüşmesiz birleşir (geometri düzenlemesi için). Her iki durumda da hiçbir şekil hareket etmez. centerline ile yok sayılır.
Uç noktalar
Üretilmiş referans — her alan, her yanıt biçimi — servisin /docs/swagger adresinde sunduğu Swagger UI'dır; OpenAPI belgesi /v3/api-docs adresinde yer alır.
Webhook'lar
İşler eşzamansız çalışır — büyük dosyalar dakikalar sürer — bu yüzden sorgulamak yerine webhook'lara abone ol. Bir uç noktayı POST /v1/webhooks ile kaydet; imzalama gizli değeri yalnızca bir kez, oluşturma anında döndürülür ve bir daha asla.
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" }
}İmzayı şöyle doğrula: ham istek gövdesinin, uç noktanın gizli değeriyle HMAC-SHA256'sını hesapla ve sabit sürede karşılaştır — uyuşmazlığı kimliği doğrulanmamış bir istek gibi ele al. Teslimat en az bir keredir: 2xx olmayan bir yanıt, üstel geri çekilmeyle üç kez yeniden denenir; bu yüzden handler'ını id üzerinde idempotent yaz. Uç noktalar herkese açık bir adrese çözülmelidir; bu, yalnızca kayıt sırasında değil, teslimat anında da yeniden kontrol edilir.
Hatalar
Başarısızlıklar JSON'dur: { "error": { "code": "…", "message": "…", "details": { … } } }. code alanına bak, mesaja değil — mesajlar yeniden yazılabilir.