Documentația API
Integrați Vectorgram în aplicația dvs. Un endpoint pentru trimitere, unul pentru poll, unul pentru descărcare — sarcinile sunt asincrone prin construcție. URL-ul de bază https://api.vectorgram.ai, autentificarea este Authorization: Bearer <api_key>. Cheile arată ca vectorgram_sk_live_… — prefixul este scris intenționat literă cu literă, astfel o cheie găsită într-un vechi .env poate fi identificată fără a fi încercată.
Un cont nou începe pe Trial cu 5 conversii gratuite — calitate completă, fără watermark — de cheltuit în browser sau prin API, dintr-un singur contor. Se dau o singură dată și nu se reînnoiesc. După aceea API-ul cere un plan care îl include (Pro și mai sus), iar apelurile se scad din alocația lunară a planului. Nu există depășiri: peste alocație, apelurile răspund 402 cu data resetării. GET /v1/account raportează fiecare alocație — inclusiv perioada de probă — și cât a rămas din fiecare.
Start rapid
1 — Luați cheia API
Se încarcă…
2 — Trimiteți o imagine
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"Răspunsul este 202 Accepted cu o sarcină pusă în coadă — conversia încă nu s-a întâmplat. Trimițând aceeași cerere de două ori cu un singur Idempotency-Key , se returnează prima sarcină în loc să se facă a doua; schimbarea fișierului sau a setărilor sub o cheie deja folosită este un 409.
3 — Poll-ați sau luați un 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 parcurge queued → processing → completed | failed | canceled | expired. Cât e în coadă primiți o queue_position reală, nu o numărătoare inventată; progress în timpul procesării se interpolează din estimarea de mărime și se oprește la 95% până există fișierul. Imaginile mari pot dura minute — interogați la un interval rezonabil sau, mai bine, înregistrați un webhook.
4 — Descărcați
{
"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 apare doar când există un rezultat, cere același bearer token și transmite fișierul ca atașament. Cu retention=none fișierul se șterge în timp ce vi se servește — descărcați-l o singură dată.
Parametri de conversie
Toate câmpurile sunt multipart form data pe POST /v1/vectorize. Cele patru marcate manual sunt comenzile de trasare: disponibile pe Pro, Studio, Agency și Enterprise. Pe Trial și Lite sunt acceptate și apoi înlocuite cu valorile implicite, nu respinse, deci un client care le trimite întotdeauna convertește în continuare — doar că primește rezultatul automat.
Obligatoriu. Imaginea de convertit. Detectată din octeții ei, nu din numele fișierului.
Ce fel de imagine este aceasta. Implicit auto, care lasă motorul să o clasifice.
Opțional, iar svg este singura valoare. SVG este ce scrie motorul și nimic nu-l convertește în altceva — EPS, PNG, PDF, DXF și AI sunt refuzate cu 400 unsupported_output_format în loc să fie puse în coadă să eșueze.
Cât timp este păstrat rezultatul. Implicit 24h; none îl șterge după prima descărcare. Limitat la maximul planului dvs., nu respins — Trial nu poate ține un rezultat 10 zile cerând asta.
Cheia dvs. proprie de grupare, întoarsă pe sarcină și folosită ca filtru. Trimiteți o cerere per imagine. Conversia în loturi începe pe Pro (30 de fișiere, 50 pe Studio, 100 pe Agency); sub ea grupul ține un singur fișier, iar al doilea răspunde 400 batch_limit_exceeded.
Numele dosarului în care vor sta fișierele lotului pe tabloul de bord. Opțional și cere batch_id (altfel 400 invalid_folder_name); limitat ca batch_id — 128 de caractere, fără caractere de control. Primul fișier admis numește dosarul; fișierele următoare ale lotului nu-l redenumesc. Lăsat deoparte, dosarul primește data creării.
Cât din imagine supraviețuiește fuzionării regiunilor. Implicit high — pasul cel mai liber pe care motorul îl are de la 1.3.0. O valoare de slider 1–100 este acceptată și distribuită în bucket-uri.
Tratarea degradeurilor. Implicit smooth; stepped și auto lasă umplerile plate ale motorului.
Rotunjirea colțurilor. Implicit strong. O valoare de slider 0–100 este acceptată și distribuită în bucket-uri.
Ce desenează motorul. Implicit fill — fiecare formă un contur umplut. centerline desenează un singur contur deschis pe mijlocul fiecărei linii (fill="none", cu o culoare și o lățime a conturului), exact ce urmăresc ploterele, gravoarele cu laser, router-ele CNC și ploterele de tăiere vinil: o trecere per linie în loc de două contururi în jurul ei. Părțile prea groase ca să fie o linie rămân forme umplute. detail, gradients și smoothing nu se aplică și sunt ignorate. O valoare necunoscută răspunde 400.
Închiderea rosturilor, pe orice plan. Implicit true — fiecare umplere alunecă 0,75 px sub vecină, deci nicio linie subțire deschisă nu se vede între două culori. false dă partiția exactă, în care formele se întâlnesc muchie la muchie fără suprapunere (pentru editarea geometriei). Nicio formă nu se mișcă în niciun caz. Ignorat cu centerline.
Endpoint-uri
Referința generată — fiecare câmp, fiecare formă de răspuns — este Swagger UI pe care îl servește serviciul la /docs/swagger, cu documentul OpenAPI la /v3/api-docs.
Webhook-uri
Fiindcă sarcinile rulează asincron — minute pentru fișiere mari — abonați-vă la webhook-uri în loc să interogați. Înregistrați un endpoint cu POST /v1/webhooks; secretul de semnare se returnează o singură dată, la creare, și niciodată după.
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" }
}Verificați semnătura calculând HMAC-SHA256 pe corpul brut al cererii cu secretul endpoint-ului dvs. și comparând în timp constant — tratați o nepotrivire ca pe o cerere neautentificată. Livrarea este „at least once”: un răspuns non-2xx se reîncearcă de trei ori cu backoff exponențial, deci faceți handler-ul idempotent pe id. Endpoint-urile trebuie să rezolve către o adresă publică; asta se reverifică la momentul livrării, nu doar la înregistrare.
Erori
Eșecurile sunt JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Citiți code, nu mesajul — mesajele se reformulează.