API-dokumentaatio
Integroi Vectorgram sovellukseen. Yksi päätepiste lähettämiseen, yksi kyselyyn, yksi lataamiseen — työt ovat rakenteeltaan asynkronisia. Perus-URL https://api.vectorgram.ai, todennus on Authorization: Bearer <api_key>. Avaimet ovat muotoa vectorgram_sk_live_… — etuliite on kirjoitettu tarkoituksella kokonaan ulos, jotta vanhasta .env löytynyt avain tunnistetaan ilman kokeilua.
Uusi tili saa 25 API-muunnosta ilmaiseksi 30 päivän ajan — täysi laatu, ei vesileimaa. Sen jälkeen API vaatii sen sisältävän paketin (Pro ja siitä ylöspäin), ja kutsut kulkevat kyseisen paketin kuukausikiintiöstä. Ylimaksua ei ole: kiintiön ylittävät kutsut vastaavat 402 nollauspäivämäärän kera. GET /v1/account ilmoittaa molemmat kiintiöt ja sen, mitä kummastakin on jäljellä.
Pikaopas
1 — Hae API-avain
Ladataan…
2 — Lähetä kuva
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"Vastauksena on 202 Accepted ja jonossa odottava työ — muunnosta ei ole vielä tehty. Sama pyyntä toisen kerran samalla Idempotency-Key palauttaa ensimmäisen työn uuden tekemisen sijaan; tiedoston tai asetusten vaihtaminen jo käytetyllä avaimella on 409.
3 — Kysy tilaa tai ota webhook vastaan
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 etenee queued → processing → completed | failed | canceled | expired. Jonossa ollessa näkyvissä on oikea queue_position eikä keksittyä lähtölaskentaa; progress käsittelyn aikana arvioidaan kokoennusteesta ja pysähtyy 95 %:iin, kunnes tiedosto on olemassa. Suuret kuvat voivat kestää minuutteja — kysy tilaa järkevällä välillä tai vielä paremmin rekisteröi webhook.
4 — Lataa tulos
{
"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 näkyy vasta, kun tulos on olemassa, vaatii saman bearer-tunnuksen ja toimitaa tiedoston liitteenä. Asetuksella retention=none tiedosto poistetaan samalla, kun se toimitetaan — lataa se siis kerralla.
Muunnosparametrit
Kaikki kentät ovat multipart-lomakedataa päätepisteessä POST /v1/vectorize. Neljä merkinnällä manuaalinen varustettua ovat jäljityksen säädöt: saatavilla pakketeissa Pro, Studio, Agency ja Enterprise. Free ja Lite hyväksyvät ne ja korvaavat oletuksilla hylkäämättä, joten asiakasohjelma, joka lähettää ne aina, saa silti muunnoksen — tulos on vain automaattinen.
Pakollinen. Muunnettava kuva. Tunnistetaan tiedoston tavuista, ei nimistä.
Millainen kuva on kyseessä. Oletus auto, jolloin moottori luokittelee sen itse.
Valinnainen, ja svg on ainoa arvo. SVG on se, mitä moottori kirjoittaa, eikä mikään muunna sitä muiksi muodoiksi — EPS, PNG, PDF, DXF ja AI hylätään virheellä 400 unsupported_output_format sen sijaan, että ne asetettaisiin jonoon epäonnistumaan.
Kuinka kauan tulos säilytetään. Oletus 24h; none poistaa sen ensimmäisen latauksen jälkeen. Rajataan paketin enimmäiseen säilytysaikaan eikä hylätä — Free ei säilytä tulosta 10 päivää, vaikka sitä pyytäisi.
Oma ryhmittelyavain, joka kaikuu työn mukana ja kelpaa suodattimeksi. Lähetä yksi pyyntö per kuva. Eräajo alkaa paketista Pro (30 tiedostoa, Studiossa 50, Agencyssä 100); sitä alempana ryhmään mahtuu yksi tiedosto, ja toinen vastaa virheellä 400 batch_limit_exceeded.
Kansion nimi, johon erän tiedostot asettuvat kojelaudassa. Valinnainen ja vaatii batch_id:n (muuten 400 invalid_folder_name); rajattu kuten batch_id — 128 merkkiä, ei ohjausmerkkejä. Ensimmäinen hyväksytty tiedosto nimeää kansion; erän myöhemmät tiedostot eivät nimeä sitä uudelleen. Jätettynä pois kansio leimataan luontipäivämäärällään.
Kuinka suuri osa kuvasta selviää alueiden yhdistämisestä. Oletus high — moottorin väljin askel version 1.3.0 jälkeen. Liukusäätimen arvo 1–100 hyväksytään ja ryhmitellään.
Liukuvärien käsittely. Oletus smooth; stepped ja auto jättävät moottorin tasaiset täytöt.
Kulmien pyöristys. Oletus strong — aidot kulmat pysyvät terävinä: palautuu vain se, mitä jäljitys pyöristi vahingossa. Liukusäätimen arvo 0–100 hyväksytään ja ryhmitellään.
Mitä moottori piirtää. Oletus fill — jokainen muoto on täytetty ääriviiva. centerline piirtää yhden avoimen viivan kunkin linjan keskelle (fill="none", viivan värillä ja leveydellä), mitä plotterit, laserkaivertimet, CNC-jyrsimet ja vinyylileikkurit seuraavat: yksi veto per viiva kahden ääriviivan sijaan. Liian paksut kohdat pysyvät täytettyinä muotoina. detail, gradients ja smoothing eivät koske sitä, ja ne ohitetaan. Tuntematon arvo vastaa virheellä 400.
Saumojen sulkeminen, kaikissa paketeissa. Oletus true — jokainen täyttö jatkuu 0,75 px naapurinsa alle, joten kahden värin väliin ei ilmesty ohutta vaaleaa viivaa. false antaa tarkan jaon, jossa muodot kohtaavat reuna toisessa ilman päällekkäisyyttä (geometrian muokkaamiseen). Mikään muoto ei liiku kummallakaan. Ohitetaan, kun käytössä on centerline.
Päätepisteet
Generoitu referenssi — jokainen kenttä, jokainen vastauksen muoto — on Swagger-käyttöliittymä, jonka palvelu tarjoaa osoitteessa /docs/swagger, ja OpenAPI-dokumentti on osoitteessa /v3/api-docs.
Webhookit
Koska työt toimivat asynkronisesti — suuret tiedostot vievät minuutteja — tilaa webhookit kyselyn sijaan. Rekisteröi päätepiste kutsumalla POST /v1/webhooks; allekirjoituksen salaisuus palautetaan kerran, luonnin yhteydessä, eikä koskaan uudelleen.
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" }
}Varmista allekirjoitus laskemalla raakapyynnön rungosta HMAC-SHA256 päätepisteen salaisuudella ja vertaamalla sitä vakiomääräisessä ajassa — kohtele poikkeamaa todentamattomana pyyntönä. Toimitus on vähintään kerran: muu kuin 2xx-vastaus yritetään uudelleen kolmesti eksponentiaalisella viiveellä, joten tee käsittelijästä idempotentti suhteessa id. Päätepisteiden on ratkaistava julkiseen osoitteeseen; se tarkistetaan uudelleen toimitushetkellä, ei vain rekisteröinnissä.
Virheet
Virheet palautuvat JSONina: { "error": { "code": "…", "message": "…", "details": { … } } }. Lue code, ei viestiä — viestien sanavalintoja muutetaan.