Documentation de l'API
Intégrez Vectorgram à votre application. Un endpoint pour soumettre, un pour interroger, un pour télécharger — les jobs sont asynchrones par conception. URL de base https://api.vectorgram.ai, l'authentification est Authorization: Bearer <api_key>. Les clés ressemblent à vectorgram_sk_live_… — le préfixe est volontairement écrit en toutes lettres, pour qu'une clé trouvée dans un ancien .env puisse être identifiée sans être testée.
Un nouveau compte reçoit 25 conversions API gratuitement pendant 30 jours — qualité complète, sans filigrane. Ensuite, l'API exige un plan qui l'inclut (Pro et plus), et les appels sont décomptés du quota mensuel de ce plan. Pas de dépassement : au-delà du quota, les appels répondent 402 avec la date de réinitialisation. GET /v1/account indique les deux quotas et ce qu'il reste de chacun.
Démarrage rapide
1 — Obtenir votre clé API
Chargement…
2 — Soumettre une image
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 réponse est 202 Accepted avec un job en file d'attente — la conversion n'a pas encore eu lieu. Envoyer deux fois la même requête avec une même Idempotency-Key renvoie le premier job au lieu d'en créer un second ; changer le fichier ou les réglages sous une clé déjà utilisée est un 409.
3 — Interroger, ou recevoir 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 passe par queued → processing → completed | failed | canceled | expired. En file d'attente, vous recevez un queue_position réel plutôt qu'un compte à rebours inventé ; progress pendant le traitement est interpolé à partir de l'estimation de taille et plafonne à 95 % jusqu'à ce que le fichier existe. Les images volumineuses peuvent prendre des minutes — interrogez à intervalle raisonnable ou, mieux, enregistrez un webhook.
4 — Télécharger
{
"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'apparaît qu'une fois qu'un résultat existe, exige le même jeton bearer et sert le fichier en pièce jointe. Avec retention=none le fichier est supprimé à mesure qu'il est servi — téléchargez-le une seule fois.
Paramètres de conversion
Tous les champs sont des multipart form data sur POST /v1/vectorize. Les quatre champs marqués manuel sont les réglages de tracé : disponibles sur Pro, Studio, Agency et Enterprise. Sur Free et Lite, ils sont acceptés puis remplacés par les valeurs par défaut au lieu d'être rejetés — un client qui les envoie toujours convertit donc quand même ; il obtient simplement le résultat automatique.
Obligatoire. L'image à convertir. Détectée à partir de ses octets, non de son nom de fichier.
Le type d'image en question. Par défaut auto, qui laisse le moteur la classifier.
Facultatif, et svg est la seule valeur. Le SVG est ce que le moteur écrit, et rien ne le convertit en autre chose — EPS, PNG, PDF, DXF et AI sont refusés avec 400 unsupported_output_format plutôt que mis en file d'attente pour échouer.
Combien de temps le résultat est conservé. Par défaut 24h ; none le supprime après le premier téléchargement. Limité au maximum de votre plan plutôt que rejeté — Free ne peut pas conserver un résultat 10 jours rien qu'en le demandant.
Votre propre clé de regroupement, renvoyée sur le job et utilisable comme filtre. Soumettez une requête par image. La conversion par lots démarre à partir de Pro (30 fichiers, 50 avec Studio, 100 avec Agency) ; en dessous, le groupe ne contient qu'un fichier et un second répond 400 batch_limit_exceeded.
Le nom du dossier dans lequel les fichiers du lot se trouveront sur le tableau de bord. Facultatif et exige batch_id (sinon 400 invalid_folder_name) ; borné comme batch_id — 128 caractères, aucun caractère de contrôle. Le premier fichier admis nomme le dossier ; les fichiers suivants du lot ne le renomment pas. S'il est omis, le dossier porte sa date de création.
La part de l'image qui survit à la fusion des régions. Par défaut high — l'étape la plus lâche du moteur depuis la 1.3.0. Une valeur de curseur 1–100 est acceptée et classée par paliers.
Traitement des dégradés. Par défaut smooth ; stepped et auto laissent les aplats du moteur.
Arrondi des angles. Par défaut strong — les angles réels restent nets, seul revient ce que le moteur a arrondi par accident. Une valeur de curseur 0–100 est acceptée et classée par paliers.
Ce que le moteur dessine. Par défaut fill — chaque forme est un contour rempli. centerline dessine un trait ouvert unique le long du milieu de chaque ligne (fill="none", avec une couleur et une épaisseur de trait), que suivent les plotters, graveuses laser, fraiseuses CNC et découpeuses de vinyle : une passe par ligne au lieu de deux contours autour. Les parties trop épaisses pour être une ligne restent des formes remplies. detail, gradients et smoothing ne s'appliquent pas et sont ignorés. Une valeur inconnue répond 400.
Fermeture des jointures, sur tous les plans. Par défaut true — chaque remplissage court 0,75 px sous son voisin, si bien qu'aucune fine ligne claire n'apparaît entre deux couleurs. false donne la partition exacte, où les formes se joignent bord à bord sans chevauchement (pour éditer la géométrie). Aucune forme ne bouge dans un cas comme dans l'autre. Ignoré avec centerline.
Endpoints
La référence générée — chaque champ, chaque forme de réponse — est l'interface Swagger que le service expose à l'adresse /docs/swagger, avec le document OpenAPI à l'adresse /v3/api-docs.
Webhooks
Comme les jobs s'exécutent de façon asynchrone — des minutes pour les gros fichiers — abonnez-vous aux webhooks plutôt que d'interroger. Enregistrez un endpoint avec POST /v1/webhooks ; le secret de signature n'est renvoyé qu'une fois, à la création, jamais ensuite.
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" }
}Vérifiez la signature en calculant le HMAC-SHA256 du corps brut de la requête avec le secret de votre endpoint et en le comparant en temps constant — traitez toute divergence comme une requête non authentifiée. La livraison se fait au moins une fois : une réponse non 2xx est réessayée trois fois avec un backoff exponentiel, rendez donc votre gestionnaire idempotent sur id. Les endpoints doivent pointer vers une adresse publique ; c'est revérifié au moment de la livraison, pas seulement à l'enregistrement.
Erreurs
Les échecs sont du JSON : { "error": { "code": "…", "message": "…", "details": { … } } }. Lisez code, pas le message — les messages sont reformulés.