Docs

API REFERENCE

Vectorize

One call: an image in, its SVG out, waited for in the same request.

POST/v1/vectorize

Vectorize an image

Converts one image and hands you its SVG in the same request. Send exactly one of file (multipart), url or inputKey. If it finishes within wait seconds the answer is 200 with the result and its files; otherwise 202 with the conversion, which finishes on its own (Location names it: read it, stream its events, or await your webhook). Every client MUST handle the 202: most images take seconds, a few take minutes. It always UNLOCKS: 1 credit per image, held now and refunded if the conversion fails; an image already unlocked costs nothing again. Past your limit of conversions at once it waits its turn instead of refusing. Test keys: free (the sample result). With Accept: image/svg+xml a finished conversion answers 303 to the web file itself.

Headers

Idempotency-Keystring
Retry safely: the same key answers the conversion it already made, never a second one and never a second charge (8–200 letters, digits and ._:~-). The same key with another image is 409 idempotency_key_reused.
Acceptstring
image/svg+xml: a finished conversion answers 303 to its web file. Follow it to take the file.

Body

JSON, or form data with the image as its file part.

urlstring
An https link to the image: we fetch it, up to 10 MB in 10 seconds, public addresses only, at most 3 redirects.
inputKeystring
An upload you already made (POST /uploads), for files up to 10 MB.
waitinteger, 0 to 60default 30
Seconds to hold the request open for the result. 0 answers at once (202): use it with a webhook.
presetone of default
optionsobject
Optional choices about this image beside its preset. {} for none. Two conversions share a cached result only with the same options. Not offered yet: merge (a redraw that merges two colors is not offered yet; merge them in the Colors tab, or ask for fewer colors).
filenamestring
OPTIONAL: the image's name, kept as its label and the download's name. Default: the file's or the URL's own.

Errors

StatusCodeWhat to do
402insufficient_creditsBuy credits, then send the same request again.
402unlock_requiredUnlock it (1 credit, once per image), then download.
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409idempotency_key_reusedMake a new key for a new request.
409unlock_pendingWait for that conversion to finish.
429free_capacity_reachedCome back after Retry-After (UTC midnight), or unlock with a credit.
429free_limit_reachedCome back after Retry-After (UTC midnight), or unlock with a credit.

Every refusal carries its code and a requestId. Errors and retries.

your key in VECSNAP_API_KEY
curl -X POST https://api.vecsnap.com/v1/vectorize \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -F file=@logo.png
example answers
{
  "object": "conversion",
  "id": "00000000-0000-4000-8000-000000000000",
  "livemode": false,
  "status": "completed",
  "phase": null,
  "preset": "default",
  "options": {},
  "imageId": "00000000-0000-4000-8000-000000000001",
  "filename": "logo",
  "inputFormat": null,
  "unlocked": true,
  "allowance": "credit",
  "engineVersion": "sample-27a924dbb20e",
  "result": {
    "anchorPoints": 29,
    "fileSize": 550,
    "formats": [
      {
        "background": "dropped",
        "bytes": 550,
        "currentColor": false,
        "default": true,
        "editableText": false,
        "id": "web",
        "profile": "web"
      },
      {
        "background": "kept",
        "bytes": 600,
        "currentColor": false,
        "default": false,
        "editableText": false,
        "id": "web-background",
        "profile": "web"
      },
      {
        "background": "dropped",
        "bytes": 759,
        "currentColor": false,
        "default": true,
        "editableText": false,
        "id": "design",
        "profile": "design"
      },
      {
        "background": "kept",
        "bytes": 823,
        "currentColor": false,
        "default": false,
        "editableText": false,
        "id": "design-background",
        "profile": "design"
      }
    ]
  },
  "failure": null,
  "inputDeletedAt": null,
  "createdAt": "2026-10-24T12:00:00.000Z",
  "updatedAt": "2026-10-24T12:00:00.000Z",
  "files": {
    "web": "https://files.vecsnap.com/…/web.svg",
    "web-background": "https://files.vecsnap.com/…/web-background.svg",
    "design": "https://files.vecsnap.com/…/design.svg",
    "design-background": "https://files.vecsnap.com/…/design-background.svg"
  },
  "filesExpireAt": "2026-10-24T12:00:00.000Z"
}