Dokumentacja API
Zintegruj Vectorgram ze swoją aplikacją. Jeden endpoint do wysyłania, jeden do odpytywania, jeden do pobierania — joby są z założenia asynchroniczne. Bazowy URL https://api.vectorgram.ai, uwierzytelnianie to Authorization: Bearer <api_key>. Klucze wyglądają tak: vectorgram_sk_live_… — prefiks zapisano celowo wprost, więc klucz znaleziony w starym .env można zidentyfikować bez wypróbowywania.
Nowe konto otrzymuje 25 darmowych konwersji API przez 30 dni — pełna jakość, bez znaku wodnego. Potem API wymaga planu, który je obejmuje (Pro i wyższe), a wywołania schodzą z miesięcznego limitu tego planu. Nie ma naliczania nadwyżek: po przekroczeniu limitu wywołania odpowiadają 402 z datą resetu. GET /v1/account podaje oba limity i to, ile z każdego pozostało.
Szybki start
1 — Zdobądź klucz API
Wczytywanie…
2 — Wyślij obraz
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"Odpowiedzią jest 202 Accepted z jobem w kolejce — konwersja jeszcze nie nastąpiła. Wysłanie tego samego żądania dwa razy z jednym Idempotency-Key zwraca pierwszy job, zamiast tworzyć drugi; zmiana pliku lub ustawień pod kluczem, który był już używany, to 409.
3 — Odpytuj albo odbierz 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 przechodzi przez queued → processing → completed | failed | canceled | expired. Dopóki job czeka w kolejce, dostajesz prawdziwy queue_position zamiast zmyślonego odliczania; progress w trakcie przetwarzania jest interpolowany z szacowanego rozmiaru i utrzymywany na 95%, dopóki plik nie istnieje. Duże obrazy mogą zająć minuty — odpytuj w rozsądnym interwale albo, jeszcze lepiej, zarejestruj webhook.
4 — Pobierz
{
"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 pojawia się dopiero, gdy istnieje wynik, wymaga tego samego tokena bearer i przesyła plik jako załącznik. Z retention=none plik jest usuwany w trakcie serwowania — pobierz go jednorazowo.
Parametry konwersji
Wszystkie pola to multipart form data na POST /v1/vectorize. Cztery pola oznaczone ręczny to sterowanie odrysowaniem: dostępne na Pro, Studio, Agency i Enterprise. Na Free i Lite są przyjmowane, po czym zastępowane wartościami domyślnymi, zamiast być odrzucane — klient, który zawsze je wysyła, nadal skonwertuje obraz; dostanie po prostu wynik automatyczny.
Wymagane. Obraz do konwersji. Rozpoznawany po bajtach, nie po nazwie pliku.
Jakiego rodzaju jest to obraz. Domyślnie auto, co pozwala silnikowi samemu go sklasyfikować.
Opcjonalny, a svg to jedyna wartość. SVG jest tym, co zapisuje silnik, i nic nie konwertuje go na nic innego — EPS, PNG, PDF, DXF i AI są odrzucane z 400 unsupported_output_format, zamiast trafiać do kolejki, żeby polec.
Jak długo wynik jest przechowywany. Domyślnie 24h; none usuwa go po pierwszym pobraniu. Przycinany do maksimum twojego planu, zamiast być odrzucany — Free nie utrzyma wyniku 10 dni tylko dlatego, że o to poproszono.
Własny klucz grupowania, zwracany przy jobie i użyteczny jako filtr. Wysyłaj jedno żądanie na obraz. Konwersja wsadowa zaczyna się od Pro (30 plików, 50 na Studio, 100 na Agency); poniżej grupa mieści jeden plik, a drugi dostaje odpowiedź 400 batch_limit_exceeded.
Nazwa folderu, w którym na panelu będą leżały pliki partii. Opcjonalny i wymaga batch_id (inaczej 400 invalid_folder_name); ograniczony jak batch_id — 128 znaków, bez znaków kontrolnych. Pierwszy przyjęty plik nadaje folderowi nazwę; kolejne pliki partii nie zmieniają jej. Gdy go pominiesz, folder dostaje znacznik swojej daty utworzenia.
Ile obrazu przetrwa scalanie regionów. Domyślnie high — najluźniejszy stopień silnika od wersji 1.3.0. Wartość suwaka 1–100 jest przyjmowana i przypisywana do progów.
Obsługa gradientów. Domyślnie smooth; stepped i auto pozostawiają płaskie wypełnienia silnika.
Zaokrąglanie narożników. Domyślnie strong — prawdziwe narożniki zostają ostre, wraca tylko to, co silnik zaokrąglił przypadkiem. Wartość suwaka 0–100 jest przyjmowana i przypisywana do progów.
Co rysuje silnik. Domyślnie fill — każda figura to wypełniony kontur. centerline rysuje jedną otwartą kreskę wzdłuż środka każdej linii (fill="none", z kolorem i grubością kreski), za którą podążają plotery, grawery laserowe, frezarki CNC i plotery tnące: jeden przejazd na linię zamiast dwóch konturów wokół niej. Części zbyt grube, by być linią, pozostają wypełnionymi figurami. detail, gradients i smoothing nie mają zastosowania i są ignorowane. Nieznana wartość odpowiada 400.
Zamykanie szwów, na każdym planie. Domyślnie true — każde wypełnienie biegnie 0,75 px pod swoim sąsiadem, więc między dwoma kolorami nie widać cienkiej jasnej linii. false daje dokładny podział, w którym figury stykają się krawędź w krawędź bez nakładania (do edycji geometrii). W obu przypadkach żadna figura się nie przesuwa. Ignorowane przy centerline.
Endpointy
Wygenerowana referencja — każde pole, każdy kształt odpowiedzi — to Swagger UI, który serwis udostępnia pod /docs/swagger, z dokumentem OpenAPI pod /v3/api-docs.
Webhooki
Ponieważ joby działają asynchronicznie — duże pliki potrafią zająć minuty — subskrybuj webhooki zamiast odpytywać. Zarejestruj endpoint przez POST /v1/webhooks; sekret podpisujący zwracany jest raz, przy utworzeniu, i nigdy więcej.
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" }
}Zweryfikuj podpis, licząc HMAC-SHA256 z surowego ciała żądania sekretem swojego endpointa i porównując w stałym czasie — rozbieżność traktuj jak żądanie nieuwierzytelnione. Doręczenie jest co najmniej jednokrotne: odpowiedź inna niż 2xx jest ponawiana trzy razy z wykładniczym backoffem, uczyń więc swoją funkcję obsługi idempotentną względem id. Endpointy muszą rozwiązywać się do adresu publicznego; sprawdzane jest to ponownie w momencie doręczenia, nie tylko przy rejestracji.
Błędy
Niepowodzenia mają postać JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Czytaj code, a nie komunikat — komunikaty bywają przeformułowywane.