API-Dokumentation
Integriere Vectorgram in deine Anwendung. Ein Endpoint zum Senden, einer zum Abfragen, einer zum Herunterladen — Jobs sind von vornherein asynchron angelegt. Basis-URL https://api.vectorgram.ai, die Authentifizierung läuft über Authorization: Bearer <api_key>. Schlüssel sehen aus wie vectorgram_sk_live_… — der Präfix wird absichtlich ausgeschrieben, damit sich ein Schlüssel, der in einer alten .env auftaucht, identifizieren lässt, ohne ihn auszuprobieren.
Ein neues Konto erhält 25 API-Konvertierungen für 30 Tage gratis — volle Qualität, ohne Wasserzeichen. Danach braucht die API einen Tarif, der sie enthält (Pro und höher), und die Aufrufe gehen von dessen monatlichem Kontingent ab. Es gibt keinen Überverbrauch: Jenseits des Kontingents antworten die Aufrufe mit 402 samt dem Zurücksetzungsdatum. GET /v1/account meldet beide Kontingente und, was von jedem übrig ist.
Schnellstart
1 — API-Schlüssel besorgen
Lädt…
2 — Ein Bild übermitteln
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"Die Antwort ist 202 Accepted mit einem Job in der Warteschlange — die Konvertierung hat noch nicht stattgefunden. Schickst du dieselbe Anfrage zweimal mit demselben Idempotency-Key, kommt der erste Job zurück, statt einen zweiten zu erzeugen; änderst du unter einem bereits verwendeten Schlüssel Datei oder Einstellungen, ist das ein 409.
3 — Abfragen oder Webhook nehmen
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 durchläuft queued → processing → completed | failed | canceled | expired. Während der Job in der Warteschlange liegt, bekommst du eine echte queue_position statt eines erfundenen Countdowns; progress wird während der Verarbeitung aus der Größenschätzung interpoliert und deckelt sich bei 95%, bis die Datei existiert. Große Bilder können Minuten dauern — frage in vernünftigem Abstand ab oder, besser, registriere einen Webhook.
4 — Herunterladen
{
"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 erscheint erst, sobald ein Ergebnis existiert, verlangt denselben Bearer-Token und streamt die Datei als Anhang. Mit retention=none wird die Datei beim Ausliefern gelöscht — lade sie einmal herunter.
Konvertierungsparameter
Alle Felder sind Multipart-Formulardaten an POST /v1/vectorize. Die vier mit manuell markierten sind die Regler fürs Nachzeichnen: verfügbar auf Pro, Studio, Agency und Enterprise. Auf Free und Lite werden sie angenommen und dann durch die Standardwerte ersetzt statt abgewiesen, sodass ein Client, der sie immer mitschickt, trotzdem konvertiert — er bekommt eben nur das automatische Ergebnis.
Erforderlich. Das zu konvertierende Bild. Wird aus seinen Bytes erkannt, nicht aus dem Dateinamen.
Um welche Art Bild es sich handelt. Standard auto — die Engine klassifiziert dann selbst.
Optional, und svg ist der einzige Wert. SVG ist, was die Engine schreibt, und nichts konvertiert es in etwas anderes — EPS, PNG, PDF, DXF und AI werden mit 400 unsupported_output_format abgewiesen, statt zum Scheitern in die Warteschlange gestellt zu werden.
Wie lange das Ergebnis aufbewahrt wird. Standard 24h; none löscht es nach dem ersten Herunterladen. Wird auf das Maximum deines Tarifs begrenzt statt abgewiesen — Free hält ein Ergebnis nicht 10 Tage, nur weil man darum bittet.
Dein eigener Gruppierungsschlüssel, wird am Job zurückgespiegelt und lässt sich als Filter nutzen. Eine Anfrage pro Bild senden. Stapel-Konvertierung beginnt bei Pro (30 Dateien, 50 bei Studio, 100 bei Agency); darunter fasst die Gruppe eine Datei, und eine zweite antwortet mit 400 batch_limit_exceeded.
Der Name des Ordners, in dem die Dateien des Stapels im Dashboard liegen werden. Optional und verlangt batch_id (sonst 400 invalid_folder_name); begrenzt wie batch_id — 128 Zeichen, keine Steuerzeichen. Die erste angenommene Datei benennt den Ordner; spätere Dateien des Stapels benennen ihn nicht um. Fehlt er, bekommt der Ordner sein Erstellungsdatum aufgestempelt.
Wie viel vom Bild das Zusammenführen von Regionen übersteht. Standard high — die großzügigste Stufe, die die Engine seit 1.3.0 hat. Ein Sliderwert von 1–100 wird akzeptiert und eingeordnet.
Verlaufbehandlung. Standard smooth; stepped und auto belassen die flachen Fills der Engine.
Eckenrundung. Standard strong — echte Ecken bleiben scharf, nur was der Tracer versehentlich abgerundet hat, kommt zurück. Ein Sliderwert von 0–100 wird akzeptiert und eingeordnet.
Was die Engine zeichnet. Standard fill — jede Form ein gefüllter Umriss. centerline zeichnet einen offenen Strich entlang der Mitte jeder Linie (fill="none", mit Strichfarbe und -breite), dem Plotter, Lasergravierer, CNC-Fräsen und Vinylplotter folgen: ein Durchgang pro Linie statt zwei Konturen darum herum. Teile, die zu dick für eine Linie sind, bleiben gefüllte Formen. detail, gradients und smoothing finden keine Anwendung und werden ignoriert. Ein unbekannter Wert antwortet mit 400.
Nahtschließung, in jedem Tarif. Standard true — jede Füllung läuft 0,75 px unter ihre Nachbarin, sodass zwischen zwei Farben keine dünne helle Linie sichtbar wird. false liefert die exakte Aufteilung, bei der Formen kantengenau ohne Überlappung aufeinandertreffen (zum Bearbeiten der Geometrie). Keine Form wird in beiden Fällen verschoben. Wird mit centerline ignoriert.
Endpoints
Die generierte Referenz — jedes Feld, jede Antwortstruktur — ist die Swagger-UI, die der Dienst unter /docs/swagger bereitstellt; das OpenAPI-Dokument liegt unter /v3/api-docs.
Webhooks
Da Jobs asynchron laufen — bei großen Dateien Minuten —, abonniere Webhooks, statt zu pollen. Registriere einen Endpoint mit POST /v1/webhooks; das Signatur-Secret wird einmalig bei der Erstellung zurückgegeben und nie wieder.
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" }
}Verifiziere die Signatur, indem du HMAC-SHA256 über den rohen Request-Body mit deinem Endpoint-Secret berechnest und sie in konstanter Zeit vergleichst — behandle eine Abweichung als unauthentifizierte Anfrage. Die Zustellung erfolgt mindestens einmal: Eine Nicht-2xx-Antwort wird dreimal mit exponentiellem Backoff wiederholt, mache deinen Handler also idempotent auf id. Endpoints müssen sich zu einer öffentlichen Adresse auflösen; das wird zur Zustellungszeit erneut geprüft, nicht nur bei der Registrierung.
Fehler
Fehler kommen als JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Lies code, nicht die Nachricht — Nachrichten werden umformuliert.