API-documentatie
Integreer Vectorgram in je applicatie. Eén endpoint om in te dienen, één om te pollen, één om te downloaden — jobs zijn asynchroon door het ontwerp. De basis-URL is https://api.vectorgram.ai, authenticatie gaat met Authorization: Bearer <api_key>. Sleutels zien eruit als vectorgram_sk_live_… — het voorvoegsel is met opzet voluit gespeld, zodat een sleutel die in een oude .env opduikt, te herkennen is zonder hem te proberen.
Een nieuw account krijgt 25 API-conversies 30 dagen gratis — volledige kwaliteit, geen watermerk. Daarna heeft de API een abonnement nodig dat hem bevat (Pro en hoger), en de aanroepen gaan van het maandelijkse quotum van dat abonnement af. Er is geen overage: boven het quotum antwoorden aanroepen met 402 inclusief de resetdatum. GET /v1/account toont beide quota en wat er van elk over is.
Snelstart
1 — Haal je API-sleutel op
Laden…
2 — Dien een afbeelding in
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"Het antwoord is 202 Accepted met een job in de wachtrij — de conversie heeft nog niet plaatsgevonden. Stuur je hetzelfde verzoek tweemaal met dezelfde Idempotency-Key, dan krijg je de eerste job terug in plaats van een tweede; het bestand of de instellingen wijzigen onder een al gebruikte sleutel geeft een 409.
3 — Poll, of neem een 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 doorloopt queued → processing → completed | failed | canceled | expired. In de wachtrij krijg je een echte queue_position te zien in plaats van een verzonnen aftelling; progress tijdens het verwerken wordt geïnterpoleerd uit de grootte-inschatting en blijft op 95% totdat het bestand er is. Grote afbeeldingen kunnen minuten duren — poll op een verstandig interval of, beter, registreer een webhook.
4 — Download
{
"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 verschijnt pas zodra er een resultaat is, heeft dezelfde bearer-token nodig en streamt het bestand als bijlage. Met retention=none wordt het bestand verwijderd zodra het wordt geleverd — download het één keer.
Conversieparameters
Alle velden zijn multipart-formuliergegevens op POST /v1/vectorize. De vier die met handmatig gemarkeerd zijn, zijn de traceerregelaars: beschikbaar op Pro, Studio, Agency en Enterprise. Op Free en Lite worden ze geaccepteerd en daarna vervangen door de standaardwaarden in plaats van geweigerd, zodat een client die ze altijd meestuurt nog steeds converteert — die krijgt alleen het automatische resultaat.
Verplicht. De afbeelding om te converteren. Herkend aan de bytes, niet aan de bestandsnaam.
Wat voor afbeelding dit is. Standaard auto, waarmee de motor hem zelf indelt.
Optioneel, en svg is de enige waarde. SVG is wat de motor schrijft en niets zet het om in iets anders — EPS, PNG, PDF, DXF en AI worden geweigerd met 400 unsupported_output_format in plaats van kansloos in de wachtrij te staan.
Hoe lang het resultaat bewaard blijft. Standaard 24h; none verwijdert het na de eerste download. Gedempt naar het maximum van je abonnement in plaats van geweigerd — Free houdt geen resultaat 10 dagen vast door erom te vragen.
Je eigen groeperingssleutel, teruggespiegeld op de job en bruikbaar als filter. Verstuur één verzoek per afbeelding. Batchconversie begint bij Pro (30 bestanden, 50 bij Studio, 100 bij Agency); daaronder bevat de groep één bestand en een tweede antwoordt met 400 batch_limit_exceeded.
De naam van de map waarin de bestanden van de batch op het dashboard komen. Optioneel en vereist batch_id (anders 400 invalid_folder_name); begrensd zoals batch_id — 128 tekens, geen stuurtekens. Het eerste toegelaten bestand geeft de map zijn naam; latere bestanden van de batch hernoemen hem niet. Laat je hem weg, dan krijgt de map zijn aanmaakdatum mee.
Hoeveel van de afbeelding het samenvoegen van gebieden overleeft. Standaard high — de meest soepele stap die de motor sinds 1.3.0 kent. Een schuifwaarde van 1–100 wordt geaccepteerd en ingedeeld.
Omgaan met verlopen. Standaard smooth; stepped en auto laten de effen vullingen van de motor staan.
Afronden van hoeken. Standaard strong — echte hoeken blijven scherp, alleen wat de tracer per ongeluk afrondde komt terug. Een schuifwaarde van 0–100 wordt geaccepteerd en ingedeeld.
Wat de motor tekent. Standaard fill — elke vorm een gevulde contour. centerline tekent één open lijn langs het midden van elke lijn (fill="none", met een lijnkleur en lijnbreedte), wat plotters, lasergraveurs, CNC-frezen en vinylsnijders volgen: één passage per lijn in plaats van twee contouren eromheen. Delen die te dik zijn voor een lijn blijven gevulde vormen. detail, gradients en smoothing zijn niet van toepassing en worden genegeerd. Een onbekende waarde antwoordt met 400.
Naden sluiten, op elk abonnement. Standaard true — elke vulling loopt 0,75 px onder zijn buur, zodat er geen dunne lichte lijn tussen twee kleuren zichtbaar is. false geeft de exacte verdeling, waarbij vormen rand aan rand elkaar raken zonder overlap (voor het bewerken van de geometrie). Geen enkele vorm verschuift, in beide gevallen. Genegeerd met centerline.
Endpoints
De gegenereerde referentie — elk veld, elke responsvorm — is de Swagger UI die de service serveert op /docs/swagger, met het OpenAPI-document op /v3/api-docs.
Webhooks
Omdat jobs asynchroon lopen — minuten voor grote bestanden — abonneer je op webhooks in plaats van te pollen. Registreer een endpoint met POST /v1/webhooks; het onderteken-secret wordt één keer teruggegeven, bij het aanmaken, en nooit meer.
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" }
}Verifieer de handtekening door de HMAC-SHA256 van de rauwe request-body te berekenen met het secret van je endpoint en die in constante tijd te vergelijken — behandel een mismatch als een niet-geauthenticeerd verzoek. Levering gebeurt minstens één keer: een niet-2xx-antwoord wordt drie keer opnieuw geprobeerd met exponentiële backoff, dus maak je handler idempotent op id. Endpoints moeten naar een publiek adres verwijzen; dat wordt bij levering opnieuw gecontroleerd, niet alleen bij registratie.
Fouten
Mislukkingen zijn JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Lees code, niet de boodschap — boodschappen worden opnieuw geformuleerd.