Documentazione dell'API
Integra Vectorgram nella tua applicazione. Un endpoint per inviare, uno per interrogare, uno per scaricare — i job sono asincroni per design. URL di base https://api.vectorgram.ai, l'autenticazione è Authorization: Bearer <api_key>. Le chiavi assomigliano a vectorgram_sk_live_… — il prefisso è scritto per esteso apposta, così una chiave trovata in un vecchio .env può essere identificata senza doverla provare.
Un nuovo account riceve 25 conversioni API gratuite per 30 giorni — qualità piena, senza filigrana. Dopodiché l'API richiede un piano che la includa (Pro e superiore), e le chiamate vengono scalate dalla quota mensile di quel piano. Nessun extra: oltre la quota, le chiamate rispondono 402 con la data di reset. GET /v1/account riporta entrambe le quote e quanto resta di ciascuna.
Avvio rapido
1 — Ottieni la tua chiave API
Caricamento…
2 — Invia un'immagine
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"La risposta è 202 Accepted con un job in coda — la conversione non è ancora avvenuta. Inviare due volte la stessa richiesta con una stessa Idempotency-Key restituisce il primo job invece di crearne un secondo; cambiare il file o le impostazioni sotto una chiave già usata è un 409.
3 — Interroga, o ricevi un 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 passa per queued → processing → completed | failed | canceled | expired. Mentre è in coda ricevi un queue_position vero invece di un conto alla rovescia inventato; progress durante l'elaborazione è interpolato dalla stima delle dimensioni e si ferma al 95% finché il file non esiste. Le immagini grandi possono richiedere minuti — interroga a intervalli ragionevoli o, meglio, registra un webhook.
4 — Scarica
{
"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 compare solo quando esiste un risultato, richiede lo stesso bearer token e invia il file in streaming come allegato. Con retention=none il file viene eliminato mentre viene servito — scaricalo una sola volta.
Parametri di conversione
Tutti i campi sono multipart form data su POST /v1/vectorize. I quattro campi contrassegnati manuale sono i controlli di tracciatura: disponibili su Pro, Studio, Agency ed Enterprise. Su Free e Lite vengono accettati e poi sostituiti con i valori predefiniti anziché rifiutati, così un client che li invia sempre converte comunque — ottiene solo il risultato automatico.
Obbligatoria. L'immagine da convertire. Rilevata dai suoi byte, non dal nome del file.
Che tipo di immagine è. Predefinito auto, che lascia al motore il compito di classificarla.
Facoltativo, e svg è l'unico valore. L'SVG è ciò che il motore scrive e nulla lo converte in altro — EPS, PNG, PDF, DXF e AI vengono rifiutati con 400 unsupported_output_format anziché messi in coda per fallire.
Per quanto tempo viene conservato il risultato. Predefinito 24h; none lo elimina dopo il primo download. Limitato al massimo consentito dal tuo piano anziché rifiutato — Free non può conservare un risultato 10 giorni solo chiedendolo.
La tua chiave di raggruppamento, riportata sul job e utilizzabile come filtro. Invia una richiesta per immagine. La conversione in batch parte da Pro (30 file, 50 su Studio, 100 su Agency); al di sotto il gruppo contiene un solo file e un secondo risponde 400 batch_limit_exceeded.
Il nome della cartella in cui si troveranno i file del batch nel pannello. Facoltativo e richiede batch_id (altrimenti 400 invalid_folder_name); con gli stessi limiti di batch_id — 128 caratteri, nessun carattere di controllo. Il primo file ammesso dà il nome alla cartella; i file successivi del batch non la rinominano. Se omesso, la cartella prende la data di creazione.
Quanta parte dell'immagine sopravvive alla fusione delle regioni. Predefinito high — il passaggio più lasco del motore dalla versione 1.3.0. Un valore di cursore 1–100 viene accettato e raggruppato in fasce.
Gestione delle sfumature. Predefinito smooth; stepped e auto lasciano i riempimenti piatti del motore.
Arrotondamento degli angoli. Predefinito strong — gli angoli veri restano nitidi e torna solo ciò che la tracciatura ha arrotondato per sbaglio. Un valore di cursore 0–100 viene accettato e raggruppato in fasce.
Cosa disegna il motore. Predefinito fill — ogni forma è un contorno riempito. centerline disegna un unico tratto aperto lungo il mezzo di ogni linea (fill="none", con colore e spessore del tratto), che è ciò che seguono plotter, incisori laser, router CNC e plotter da taglio per vinile: un passaggio per linea invece di due contorni intorno. Le parti troppo spesse per essere una linea restano forme piene. detail, gradients e smoothing non si applicano e vengono ignorati. Un valore sconosciuto risponde 400.
Chiusura delle giunzioni, su tutti i piani. Predefinito true — ogni riempimento scorre 0,75 px sotto il suo vicino, così nessuna sottile linea chiara compare tra due colori. false dà la partizione esatta, in cui le forme si incontrano bordo a bordo senza sovrapposizione (per modificare la geometria). In entrambi i casi nessuna forma si sposta. Ignorato con centerline.
Endpoint
Il riferimento generato — ogni campo, ogni forma di risposta — è la Swagger UI che il servizio espone all'indirizzo /docs/swagger, con il documento OpenAPI all'indirizzo /v3/api-docs.
Webhook
Poiché i job girano in modo asincrono — minuti per i file grandi — sottoscrivi i webhook invece di interrogare. Registra un endpoint con POST /v1/webhooks; il segreto di firma viene restituito una volta sola, alla creazione, e mai più.
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" }
}Verifica la firma calcolando l'HMAC-SHA256 del corpo grezzo della richiesta con il segreto del tuo endpoint e confrontandolo in tempo costante — tratta ogni discrepanza come una richiesta non autenticata. La consegna avviene almeno una volta: una risposta non 2xx viene ritentata tre volte con backoff esponenziale, quindi rendi il tuo handler idempotente su id. Gli endpoint devono risolvere a un indirizzo pubblico; viene riverificato al momento della consegna, non solo alla registrazione.
Errori
I fallimenti sono JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Leggi code, non il messaggio — i messaggi vengono riformulati.