Reference — API

Dokumentace API

Integrujte Vectorgram do své aplikace. Jeden endpoint na odeslání, jeden na sledování, jeden na stažení — úlohy jsou asynchronní od základu. Základní URL https://api.vectorgram.ai, ověření je Authorization: Bearer <api_key>. Klíče vypadají takto: vectorgram_sk_live_… — prefix je záměrně vyepsaný, takže klíč nalezený ve starém .env se pozná, aniž by se musel vyzkoušet.

Nový účet dostává 25 konverzí API zdarma na 30 dní — v plné kvalitě a bez vodoznaku. Poté API potřebuje tarif, který ho zahrnuje (Pro a výš), a volání se odečítají z měsíčního objemu tohoto tarifu. Doplatky za nadspotřebu neexistují: po vyčerpání objemu volání odpoví 402 s datem resetu. GET /v1/account hlásí oba objemy i to, kolik z každého zbývá.

Rychlý start

1 — Získejte klíč API

Vaše klíče API

Umožnit tomuto klíči vytvářet a odvolávat klíče (keys:write)Jen pro automatickou rotaci klíčů. Když unikne klíč bez tohoto oprávnění, stojí vás konverze; klíč s ním si umí vytvořit náhrady a odvolat ty, které vaše integrace právě používá.

Načítá se…

2 — Odešlete obrázek

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"

Odpovědí je 202 Accepted s úlohou ve frontě — konverze se zatím neuskutečnila. Když pošlete stejný požadavek dvakrát s týmž Idempotency-Key vrátí se první úloha, ne že vznikne druhá; změna souboru nebo nastavení pod už použitým klíčem je 409.

3 — Sledujte, nebo vezměte 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 prochází queued → processing → completed | failed | canceled | expired. Ve frontě dostáváte skutečné queue_position a ne vymyšlené odpočítávání; progress během zpracování se interpoluje z odhadu velikosti a stropuje na 95 %, dokud soubor nevznikne. Velké obrázky mohou trvat minuty — sledujte v rozumných intervalech, nebo ještě lépe zaregistrujte webhook.

4 — Stáhněte výsledek

{
  "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 se objeví, jakmile existuje výsledek, vyžaduje týž bearer token a posílá soubor jako přílohu. S retention=none se soubor maže v okamžiku odeslání — stáhněte si ho jednou.

Parametry konverze

Všechna pole jsou multipart form data na POST /v1/vectorize. Čtyři označená ruční jsou řídicí prvky trasování: dostupné na Pro, Studio, Agency a Enterprise. Na Free a Lite se přijmou a pak nahradí výchozími hodnotami, místo aby se odmítly, takže klient, který je posílá vždy, konvertuje dál — dostane jen automatický výsledek.

filePNG, JPEG, WebP, AVIF nebo BMP, ≤ 50 MB

Povinný. Obrázek ke konverzi. Rozpozná se z bajtů, ne z názvu souboru.

image_typeauto · clipart · photo · scan · blueprint

O jaký druh obrázku jde. Výchozí auto, které nechá klasifikaci na modulu.

output_formatsvg

Volitelný a svg je jediná hodnota. SVG je to, co modul zapisuje, a nic to nepřevádí na nic jiného — EPS, PNG, PDF, DXF a AI se odmítají s 400 unsupported_output_format, místo aby čekaly ve frontě na selhání.

retentionnone · 24h · 3d · 7d · 10d

Jak dlouho se výsledek uchovává. Výchozí 24h; none ho smaže po prvním stažení. Přizpůsobí se maximu vašeho tarifu, místo aby se odmítl — Free nedrží výsledek 10 dní jen tím, že o to požádá.

batch_idlibovolný řetězec

Vlastní klíč pro seskupení, vrací se v úloze a jde použít jako filtr. Na každý obrázek posílejte jeden požadavek. Dávková konverze začíná na Pro (30 souborů, 50 na Studio, 100 na Agency); pod ním drží skupina jeden soubor a druhý odpoví 400 batch_limit_exceeded.

folder_namelibovolný řetězec

Název složky, ve které budou soubory dávky ležet na dashboardu. Volitelný a vyžaduje batch_id (jinak 400 invalid_folder_name); omezený jako batch_id — 128 znaků, žádné řídicí znaky. Složku pojmenuje první přijatý soubor; další soubory dávky ji nepřejmenovávají. Bez něj se složka označí datem svého vzniku.

detailručnílow · medium · high

Kolik z obrázku přežije spojování oblastí. Výchozí high — nejslabší stupeň, který má modul od verze 1.3.0. Hodnota posuvníku 1–100 se přijme a zařadí do příslušné skupiny.

gradientsručníauto · smooth · stepped

Zacházení s přechody. Výchozí smooth; stepped a auto ponechají ploché výplně modulu.

smoothingručníoff · light · strong · maximum

Zaoblování rohů. Výchozí strong — skutečné rohy zůstávají ostré, vrátí se jen to, co trasování zaoblilo omylem. Hodnota posuvníku 0–100 se přijme a zařadí do příslušné skupiny.

trace_styleručnífill · centerline

Co modul kreslí. Výchozí fill — každý tvar jako vyplněný obrys. centerline kreslí jednu otevřenou linku po středu každé čáry (fill="none", s barvou a šířkou tahu), čímž se řídí plottery, laserové gravíry, CNC frézky a řezačky fólií: jeden průchod na čáru místo dvou obrysů kolem ní. Části příliš silné na to, aby byly čárou, zůstávají vyplněné tvary. detail, gradients a smoothing se nepoužívají a ignorují se. Neznámá hodnota odpoví 400.

close_seamstrue · false

Zavírání švů, na každém tarifu. Výchozí true — každá výplň zajíždí 0,75 px pod souseda, takže mezi dvěma barvami neprosvítá tenká světlá linka. false dává přesné rozdělení, kde se tvary stýkají hranou na hranu bez překryvu (pro úpravu geometrie). Ani jeden tvar se neposune. U centerline se ignoruje.

Endpointy

POST/v1/vectorizeOdeslat obrázek — vrací 202 + úlohu ve frontě

GET/v1/jobsVypsat úlohy — stránkování kurzorem, volitelné filtry status a batch_id

GET/v1/foldersVypsat složky účtu — kde leží soubory dávek: název, datum a aktuální počet souborů, nejnovější první

DELETE/v1/folders/{id}Smazat složku a každý soubor uvnitř — soubory ve frontě se vracejí jako u jakéhokoli jiného mazání

GET/v1/jobs/{id}Stav a průběh úlohy

GET/v1/jobs/{id}/downloadStáhnout výsledek

DELETE/v1/jobs/{id}Smazat úlohu a její soubory okamžitě

POST/v1/jobs/{id}/reportNahlásit špatný výsledek

GET/v1/accountTarif, obě kvóty s tím, kolik z každé zbývá, limit dávky a strop doby uchování

GET/v1/keysVypsat klíče API

POST/v1/keysVytvořit klíč — tajný klíč se zobrazí jednou

DELETE/v1/keys/{id}Odvolat klíč

GET/v1/webhooksVypsat webhookové endpointy

POST/v1/webhooksZaregistrovat endpoint — tajný klíč se zobrazí jednou

DELETE/v1/webhooks/{id}Smazat endpoint

Vygenerovaná reference — každé pole, každý tvar odpovědi — je Swagger UI, které služba servíruje na /docs/swagger, s dokumentem OpenAPI na /v3/api-docs.

Webhooky

Protože úlohy běží asynchronně — u velkých souborů minuty — odebírejte webhooky místo sledování. Endpoint zaregistrujete přes POST /v1/webhooks; podpisový tajný klíč se vrátí jednou, při vytvoření, a už nikdy.

processing.startedPracovník si úlohu vzal

processing.completedVýsledek je připraven ke stažení

processing.failedKonečné selhání — platba se vrátila

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" }
}

Podpis ověřte výpočtem HMAC-SHA256 nad surovým tělem požadavku s tajným klíčem endpointu a porovnáním v konstantním čase — nesoulad berte jako neověřený požadavek. Doručení je alespoň jednou: odpověď mimo 2xx se opakuje třikrát s exponenciálním čekáním, takže handler udělejte idempotentním na id. Endpointy se musí překládat na veřejnou adresu; kontroluje se to znovu při doručování, ne jen při registraci.

Chyby

Selhání jsou JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Čtěte code, ne zprávu — zprávy se přeformulovávají.

400missing_fileV požadavku chybí část `file`

400unreadable_fileČást se souborem byla přítomná, ale nedala se přečíst

400empty_fileNahraný soubor nemá žádné bajty

400batch_limit_exceededVíce souborů pod jedním batch_id, než tarif dovoluje — dávky začínají na Pro

400invalid_batch_idbatch_id je delší než 128 znaků nebo obsahuje řídicí znaky

400invalid_folder_namefolder_name je delší než 128 znaků, obsahuje řídicí znaky, nebo byl poslán bez batch_id

401unauthorizedChybějící, poškozený nebo odvolaný klíč API

402quota_exhaustedKonverze zahrnuté ve vašem tarifu pro tuto plochu jsou vyčerpané. Doplatky za nadspotřebu neexistují: podrobnosti nesou rozsah, počítadla, čas resetu a tarif, který váš objem pokryje

402megapixels_exceededObrázek je větší, než váš tarif dovoluje — odmítne se při nahrání, takže žádná konverze se nespotřebuje

402high_detail_not_includedhigh_detail byl zrušen a nezahrnuje ho žádný tarif; pošlete požadavek bez něj

403forbiddenVáš tarif nemá přístup k API a zkušební objem je vyčerpaný nebo vypršel — API začíná na Pro

404not_foundTaková úloha neexistuje — to vrátí i úloha, kterou nevlastníte

409not_readyStažení požadováno dřív, než úloha doběhla

409idempotency_key_reuseIdempotency-Key znovu použit s jiným souborem nebo nastavením

409request_in_progressTýž Idempotency-Key stále běží — zkuste to za chvíli

410result_expiredVýsledek se smazal podle své doby uchování

413file_too_largeNahrání nad 50 MB

415unsupported_formatNení PNG, JPEG, WebP, AVIF ani BMP

429too_many_active_jobsPříliš mnoho vašich úloh už běží; počkejte, až jedna doběhne

429daily_fuse_trippedStrop fair use za posledních 24 hodin na tarifu bez měření. Není co koupit — okno se posune samo

503queue_fullPlná kapacita; zkuste to znovu po sekundách z Retry-After

503storage_fullÚložiště je dočasně plné; zkuste to později