API REFERENCE

Colors

A result's colors: read them, recolor it, keep your brand's palettes.

GET/v1/conversions/{id}/paints

The result's paint map

Every tier, like the preview: the paints the file draws with its ground left out, in index order, each with its share of the frame, the ground, and a link to paints.bin: zlib of an index plane then a weight plane (width × height × 4 bytes each: every pixel's four largest paints, 255 = none, and their weights × 255). A pixel of any recolor is Σ w·c′ (premultiplied), with the ground under it as (1 − Σ w)·ground. Made with the conversion (an older result's on the first ask); a drawing of more than 24 paints has none.

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.
409too_many_colorsRedraw it with fewer colors first.
429compute_limit_reachedCome back after Retry-After (UTC midnight).
429derive_busyNothing was done. Send it again in a moment (Retry-After).
429editing_capacity_reachedCome back after Retry-After (UTC midnight), or take a plan: a customer's editing is its own.
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/paints \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "width": 1,
  "height": 1,
  "ground": "#1f6feb",
  "groundArea": 0,
  "paints": [
    {
      "key": "#1f6feb",
      "area": 0
    }
  ],
  "map": "https://files.vecsnap.com/…",
  "expiresIn": 1
}

GET/v1/conversions/{id}/palette

Preview fewer colors

Previews of a redraw with fewer colors. Without count: the WHOLE rail in one answer (counts), every count in the engine's bounds, colors only: what a client asks once, then reads. With count: the colors the engine REACHES for at most that many (from the result's kept original; it can be fewer), and the result's own colors MERGED into them (mapping), a recolor of the very drawing a client draws exactly. With format (a web file with a picture), also picture: the merged drawing at the preview's size; its deeper tiles are POST /conversions/{id}/tiles with palette. The redraw itself (POST /images/{id}/conversions with options.maxColors) traces new shapes.

Path

ididrequired

Query

countinteger, 2 to 24
One count; left out, the whole rail.
formatstring
With count, a web file's id: its merged picture too.

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.
409original_not_keptUpload the file again.
409result_outdatedConvert the image again.
429compute_limit_reachedCome back after Retry-After (UTC midnight).
429derive_busyNothing was done. Send it again in a moment (Retry-After).
429editing_capacity_reachedCome back after Retry-After (UTC midnight), or take a plan: a customer's editing is its own.
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/palette \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "counts": [
    {
      "asked": 0,
      "count": 1,
      "colors": [
        "#1f6feb"
      ],
      "mapping": {}
    }
  ]
}

GET/v1/conversions/{id}/variants

List a result's recolors

The result's recolors, the last used first: the 10 used last, in one page (hasMore says older ones exist; they are not listed, and saving one again brings it first).

Path

ididrequired

Errors

StatusCodeWhat to do
404not_foundCheck the id. Another account's objects read as not found too.

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/variants \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "edits": [
        {
          "op": "example",
          "shape": 0
        }
      ],
      "colors": {},
      "usedAt": "2026-10-24T12:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

POST/v1/conversions/{id}/variants

Change a result: recolor it, edit its shapes

A REVISION of the result. colors maps the file's own colors to new ones, every use of each (fills, strokes, gradient stops, the ground); two to one value merge them. Keys are the result's paints and its ground (/facts). edits (at most 1000; at most 25 of them slow to replay: simplify, merge, subtract, intersect, exclude, offset, outline, fillet) change its shapes, applied in order before the colors: hide, duplicate, place, simplify, round, point, corner, add_point, delete_point, fillet, merge, arrange, paint, subtract, intersect, exclude, flip, offset, outline, stretch, align. Each addresses a shape by its index in the table with the background kept; the background can only be hidden, and is no edit's other shape (into, by, with). It is stored canonical, and the same one saved again is the same variant, used now. Free; its files download under the image's unlock (/download?variant=). An edit only the engine draws, the file's own geometry (simplify, round, point, corner, add_point, delete_point, fillet, merge, subtract, intersect, exclude, offset, outline), is added once the image is unlocked (402 unlock_required before, nothing saved); one a saved revision of the result already holds is kept.

Path

ididrequired

Body

colorsobject
{"#old": "#new"}, each #rrggbb.
editsobject
Shape edits, in order: a list of at most 1000 {op, shape, …}, at most 25 of them slow (simplify, merge, subtract, intersect, exclude, offset, outline, fillet).

Errors

StatusCodeWhat to do
402unlock_requiredUnlock it (1 credit, once per image), then send the same request again.
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.
429compute_limit_reachedCome back after Retry-After (UTC midnight).
429derive_busyNothing was done. Send it again in a moment (Retry-After).
429editing_capacity_reachedCome back after Retry-After (UTC midnight), or take a plan: a customer's editing is its own.
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/variants \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"colors":{},"edits":null}'
example answers
{
  "id": "00000000-0000-4000-8000-000000000000",
  "edits": [
    {
      "op": "example",
      "shape": 0
    }
  ],
  "colors": {},
  "usedAt": "2026-10-24T12:00:00.000Z"
}

GET/v1/palettes

List palettes

The account's palettes, the last changed first: at most 20, in one page.

Errors

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

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/palettes \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
200
example answers
{
  "object": "list",
  "data": [
    {
      "object": "palette",
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Brand colors",
      "colors": [
        "#1f6feb"
      ],
      "updatedAt": "2026-10-24T12:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

POST/v1/palettes

Save a palette

A new palette; an account keeps at most 20 (409 palette_limit).

Body

namestringrequired
Trimmed.
colorsarray of stringrequired
#rrggbb, either case; a repeated one is kept once.

Errors

StatusCodeWhat to do
409palette_limitDelete a palette, then save the new one.

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/palettes \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Brand colors","colors":["example"]}'
example answers
{
  "object": "palette",
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "Brand colors",
  "colors": [
    "#1f6feb"
  ],
  "updatedAt": "2026-10-24T12:00:00.000Z"
}

PATCH/v1/palettes/{id}

Change a palette

Its name and colors, whole. Another's is 404 palette_not_found, the same as none.

Path

ididrequired

Body

namestringrequired
Trimmed.
colorsarray of stringrequired
#rrggbb, either case; a repeated one is kept once.

Errors

StatusCodeWhat to do
404palette_not_foundUse a palette id GET /palettes listed.

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

curl
your key in VECSNAP_API_KEY
curl -X PATCH https://api.vecsnap.com/v1/palettes/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $VECSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Brand colors","colors":["example"]}'
example answers
{
  "object": "palette",
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "Brand colors",
  "colors": [
    "#1f6feb"
  ],
  "updatedAt": "2026-10-24T12:00:00.000Z"
}

DELETE/v1/palettes/{id}

Delete a palette

Removed for good. Another's is 404 palette_not_found, the same as none.

Path

ididrequired

Errors

StatusCodeWhat to do
404palette_not_foundUse a palette id GET /palettes listed.

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

curl
your key in VECSNAP_API_KEY
curl -X DELETE https://api.vecsnap.com/v1/palettes/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
example answers
{
  "id": "00000000-0000-4000-8000-000000000000",
  "deleted": true
}