Docs

API REFERENCE

Results

A completed conversion's files: download one, preview it, read its figures and shapes.

GET/v1/conversions/{id}/download

Download a file of the result

A short-lived URL for one of the result's files: format names one of result.formats by id (absent, the web default). Served from the storage domain as an attachment, never inline from this origin: SVG is an active document format. Allowed once the conversion's IMAGE is unlocked, on every plan; then every format and re-download is free. A locked image answers 402 unlock_required (this GET never spends). as takes the format as a print-ready PDF (pdf, a design file's of outlines, never its editableText twin) or a picture (png, a web file's with a preview, size px on its long side): made from the stored result on first ask, after the unlock check.

Path

ididrequired

Query

formatstring
A format's id from result.formats; the web default when left out.
asone of svg, pdf, pngdefault svg
sizeone of 2048, 4096, 8192default 2048
With as=png: the picture's long side in px.
variantid
A recolor of the result (POST /conversions/{id}/variants): the file with those colors, every format but currentColor.

Errors

StatusCodeWhat to do
402unlock_requiredUnlock it (1 credit, once per image), then download.
404not_foundCheck the id. Another account's objects read as not found too.
404variant_not_foundUse a variant id this result listed.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

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

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/download \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "url": "https://files.vecsnap.com/…",
  "expiresIn": 1,
  "filename": "logo",
  "format": "example"
}

GET/v1/conversions/{id}/preview

Preview the result

A short-lived URL for a web file's rendered PNG, on EVERY tier: the free tier is the product demo, a full-quality conversion, this preview and its figures, with the SVG withheld. Served inline (a PNG is inert). format names a web file of result.formats that is not currentColor (its background kept or dropped); absent, the web default's. 2048 px on its long side, at the drawing's own aspect. layer=outline: the anchor-point view at the same size, lying exactly on it (black hairlines and squares on transparency).

Path

ididrequired

Query

formatstring
A web file's id; the web default when left out.
layerone of outline

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

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

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/preview \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "url": "https://files.vecsnap.com/…",
  "expiresIn": 1
}

POST/v1/conversions/{id}/tiles

Tiles of a deeper zoom

Every tier, like the preview: pictures of the file, never the SVG. Level L draws the drawing 2048·2^L px long, cut into 512-px squares (1 ≤ L ≤ 3); a tile is [x, y] within the square grid of its level. Missing tiles are made first, then served from storage.

Path

ididrequired

Body

layerstringrequired
outline or outline-2x (the anchor-point view drawn for a 1× or 2× screen), a web file's id, or ids-{format} (that web file's Shapes ID picture, GET /conversions/{id}/shapes).
levelinteger, 1 to 3required
tilesarray of array of anyrequired
variantid, or null
A recolor of the result: a web file's tiles with its colors (never the outline's).
paletteinteger, 2 to 24, or null
A redraw's preview count (GET /conversions/{id}/palette): a web file's tiles with the drawing merged into its colors. Never with variant.

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
404variant_not_foundUse a variant id this result listed.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409original_not_keptUpload the file again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

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

curl
your key in VECSNAP_API_KEY
curl -X POST https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/tiles \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"layer":"outline","level":1,"tiles":[[0,0]]}'
example answers
{
  "layer": "outline",
  "level": 0,
  "variant": "00000000-0000-4000-8000-000000000000",
  "palette": 0,
  "tiles": [
    {
      "x": 0,
      "y": 0,
      "url": "https://files.vecsnap.com/…"
    }
  ],
  "expiresIn": 1
}

GET/v1/conversions/{id}/original

The original image

A short-lived URL for the image the conversion was made from: the upload, kept with its result for the comparison (deleted with the result or the account, never in the shared cache). While it waits or runs, the upload itself, so a client can show the image being converted. Served inline, as the type its bytes proved at upload. A result made before originals were kept, a running conversion whose upload is gone, or a TIFF (which no browser but Safari draws) has none: 404 original_unavailable.

Path

ididrequired

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
404original_unavailableShow its redraw instead.
409conversion_failedConvert the image again. Converting is free.

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

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/original \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "url": "https://files.vecsnap.com/…",
  "expiresIn": 1
}

GET/v1/conversions/{id}/facts

The result's facts

Every tier: the engine's facts of the default file, in the ENGINE's names (the same object the site's examples show): the counts a layers panel would sum (anchor points, paths, circles, rectangles, rings, strokes, repeats, elements, the words kept as text) and every color the file draws with what it paints and its share of the frame.

Path

ididrequired

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

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

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/facts \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "summary": {
    "anchor_points": 0,
    "circles": 0,
    "rects": 0,
    "rings": 0,
    "paths": 0,
    "strokes": 0,
    "uses": 0,
    "definitions": 0,
    "elements": 0,
    "words": [
      "example"
    ],
    "colors": 0,
    "gradients": 0
  },
  "colors": [
    {
      "key": "#1f6feb",
      "roles": [
        "fill"
      ],
      "area": 0
    }
  ],
  "ground": "#1f6feb"
}

GET/v1/conversions/{id}/shapes

The result's shapes

Every tier, like the preview: a web file's shapes in the engine's order, and a link to its ID PICTURE at the preview's size: every pixel's color − 1 is the shape on top there, transparent where none is, never a blended pixel. Decode it with color conversion and premultiplying off. Its deeper zoom: POST /conversions/{id}/tiles with the layer ids-{format}. Made on the first ask, then served.

Path

ididrequired

Query

formatstring
A web file's id; the default web file when left out.

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.
409conversion_failedConvert the image again. Converting is free.
409not_in_test_modeUse a live key for it, or test the conversion and its SVG files.
409not_readyWait for it to finish (a webhook, the events stream, or a read), then ask again.
409result_outdatedConvert the image again.
429rate_limitedWait the Retry-After seconds, then send it again.
502derive_failedTry again. The coarser picture still shows.

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

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/conversions/00000000-0000-4000-8000-000000000000/shapes \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "format": "example",
  "width": 1,
  "height": 1,
  "rows": [
    {
      "index": 0,
      "kind": "example",
      "ground": false,
      "points": 0,
      "paint": "#1f6feb",
      "box": [
        0,
        0,
        0,
        0
      ],
      "neighbors": [
        0
      ]
    }
  ],
  "picture": "https://files.vecsnap.com/…",
  "expiresIn": 1
}