API PixelToPath

Guida rapida

Tre passaggi e starai convertendo immagini in SVG dal tuo terminale, dai tuoi script o dalla tua app.

La tua prima conversione

curl -sS -f -X POST https://api.pixel-to-path.com/v1/convert \
  -H "Authorization: Bearer ptp_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "colormode=binary" \
  -o logo.svg

Riferimento interattivo: pixel-to-path.com/v1/docs (OpenAPI/Swagger).

Autenticazione

Ogni richiesta è autenticata con un token Bearer nell'header Authorization:

Authorization: Bearer ptp_live_0123abc…

• Le chiavi sono segrete: vengono salvate tramite hash lato server e mostrate solo una volta al momento della creazione. Chiave smarrita? Revocala e creane una nuova.
• Un account, più chiavi: crea fino a 5 chiavi attive per separare i tuoi progetti. La quota mensile gratuita viene conteggiata per account, non per chiave.
• Revoca immediata: una chiave revocata smette di funzionare immediatamente, sia che venga revocata dal portale sia se l'account viene bannato.

POST /v1/convert

Caricamento e conversione in una singola chiamata senza stato (stateless). Una chiamata andata a buon fine costa al massimo 1 credito — le chiamate fallite, non valide o limitate dal rate limiting non costano nulla.

Richiesta (multipart/form-data)

Due motori, scelti tramite "colormode"

L'API esegue esattamente gli stessi motori del convertitore online gratuito e dell'app desktop:

Le immagini vengono pre-elaborate esattamente come sul sito web: il lato più lungo viene ridimensionato a 1500 px prima della conversione, e l'API restituisce il tipo di immagine rilevato (line_art, logo, photo o illustration) nell'header X-Detected-Type.

Risposta

In caso di successo: 200 OK con image/svg+xml — il corpo della risposta è il file SVG stesso. Header informativi:

GET /v1/me

Stato dell'account per la chiave utilizzata per chiamare questo endpoint. Gratuito — non viene mai conteggiato nella tua quota gratuita, né addebitato.

Esempio di risposta

GET /v1/me
Authorization: Bearer ptp_live_…

{
  "key": { "name": "prod", "prefix": "ptp_live_0123abc", … },
  "usage": {
    "month": "2026-09", "free_used": 7, "free_limit": 10,
    "free_remaining": 3, "resets_at": "2026-10-01T00:00:00+00:00"
  },
  "credits": { "balance": 120 }
}

Errori

Ogni errore restituisce un wrapper JSON coerente. Le chiamate fallite non consumano mai crediti.

HTTP/1.1 402 Payment Required
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly free quota used and no credits left.",
    "usage": { "free_used": 10, "free_limit": 10, "credits": 0 }
  }
}

Limiti di frequenza (Rate limits)

I limiti si applicano per chiave API, non per IP, in modo che un ufficio condiviso o un runner CI non venga mai penalizzato per il traffico di qualcun altro.

Prezzi

Ogni nuovo account riceve 10 conversioni gratuite ogni mese, senza necessità di carta di credito. Hai bisogno di più? Acquista immagini prepagate — in qualsiasi quantità (in lotti di 50), con sconti per volume. Non scadono mai e si sommano alla tua quota mensile gratuita (le conversioni gratuite vengono consumate per prime).

Accredito automatico: il tuo saldo viene aggiornato entro pochi secondi dal pagamento, tramite il webhook di pagamento. I rimborsi sottraggono i crediti acquistati, fino al limite del saldo corrente. Pagamento sicuro tramite Lemon Squeezy (IVA gestita automaticamente).

Esempi di codice

Copia, incolla e adatta. L'API usa un semplice multipart/form-data, quindi funziona con qualsiasi client HTTP.

cURL

curl -sS -f -X POST https://api.pixel-to-path.com/v1/convert \
  -H "Authorization: Bearer ptp_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "colormode=color" \
  -F "filter_speckle=4" \
  -o photo.svg

Python

import requests

resp = requests.post(
    "https://api.pixel-to-path.com/v1/convert",
    headers={"Authorization": "Bearer ptp_live_YOUR_KEY"},
    files={"file": open("photo.jpg", "rb")},
    data={"colormode": "color", "filter_speckle": 4},
)
resp.raise_for_status()
print(resp.headers["X-Credits-Remaining"], "credits left")
with open("photo.svg", "wb") as f:
    f.write(resp.content)

JavaScript

const form = new FormData();
form.append("file", new Blob([imageBytes]), "photo.jpg");
form.append("colormode", "color");

const resp = await fetch("https://api.pixel-to-path.com/v1/convert", {
  method: "POST",
  headers: { "Authorization": "Bearer ptp_live_YOUR_KEY" },
  body: form,
});
if (!resp.ok) {
  const { error } = await resp.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const svg = await resp.text();
console.log(resp.headers.get("X-Credits-Remaining"), "credits left");

Domande frequenti