One POST. An image in, a vector back.

Overview

There is no SDK to install and no job queue to poll. You POST a file to /api/v1/vectorize with your API key in a header, the request blocks while the image is traced, and the response hands back a URL to the finished file, which you then fetch — two requests, no polling in between. A typical trace takes a few seconds; a large, detailed image traced with draw_style=fill_gradients can take considerably longer, and remove_bg=true adds roughly 1-2 seconds.

• Input — PNG, JPG or WEBP, sent as multipart/form-data.
• Output — JSON holding a fileUrl, a direct download link to the traced file in storage.
• Billing — one credit per production image, and test requests are free. Failed requests are not charged. See Pricing.

Authentication

Every request carries an API key as a bearer token in the Authorization header. Keys are created and revoked on your account page — sign in, open the API keys panel, and create one. A key is shown in full whenever you reveal it, so you can copy it again later, and revoking one takes effect immediately.

Authorization: Bearer jv_live_xxxxxxxxxxxxxxxxxxxxxxxx

A missing or revoked key returns 401. An account with no credits left returns 402 — see Errors.

Pricing

What a request costs is set by its image_mode field. Leave it out and you get a production result.

A request that fails costs nothing, whatever its mode. For how each mode marks the image, see image_mode in the parameter reference.

Quickstart

The smallest useful request is a file and nothing else; every other field falls back to a default chosen to look right on a typical image. This traces logo.png and writes logo.svg:

# The response is JSON — {"fileUrl": "https://…"} — so trace, then fetch.
url=$(curl -s -X POST https://api.justvectorize.com/api/v1/vectorize \
  -H "Authorization: Bearer $JUSTVECTORIZE_API_KEY" \
  -F "file=@logo.png" \
  -F "format=svg" | jq -r .fileUrl)

curl -o logo.svg "$url"

Adding parameters is the same request with more form fields. The call below asks for a four-color DXF sized for a cutter:

# A four-color logo, cut as a DXF in millimetres, 120 mm wide, with
# every edge between shapes stroked exactly once. Straight edges and
# circular arcs are refitted as real primitives on every trace.
curl -X POST https://api.justvectorize.com/api/v1/vectorize \
  -H "Authorization: Bearer $JUSTVECTORIZE_API_KEY" \
  -F "file=@logo.png" \
  -F "format=dxf" \
  -F "n_colors=4" \
  -F "draw_style=stroke_edges" \
  -F "width=120" \
  -F "unit=mm" \
  -F "dxf_units=mm" | jq -r .fileUrl

Endpoints

One request traces one image. There is no batch endpoint — send them concurrently, a few at a time, and back off on 502.

The request

POST https://api.justvectorize.com/api/v1/vectorize with a multipart/form-data body. Do not set Content-Type yourself — your HTTP client writes it, with the multipart boundary, when you hand it a form body.

An omitted field means “use the default”, so you only ever send the knobs you actually care about. Values are validated server-side; an out-of-range one fails the whole request with 422 rather than being silently clamped, and so does a field name the API does not recognise.

Some combinations are accepted but have nothing to act on: stroke_color under a fill style, the svg_* fields with format=png, shape_stacking and group_by under stroke_edges, or scale sent together with width or height (scale wins). The trace still runs; the field is simply not used.

The response

On success the status is 200 and the body is JSON carrying a single field, fileUrl — a direct link to the traced file. Fetch it with a plain GET; that request needs no API key and costs no credit.

{
  "fileUrl": "https://storage.googleapis.com/creative-ais/Pe887UovP6-FrWIpJvi8S.svg+xml"
}

The stored file is served with the Content-Type for the format you asked for:

A failure answers with JSON too — { "error": "…" } instead of a fileUrl — so branch on the status code before you read either field.

Custom palettes

Left alone, the tracer picks the colors itself. The palette field takes that decision away from it: pass a JSON string holding a list whose entries are either plain color strings, or objects that also say how far each entry reaches and what its matches become.

# Straighten near-misses of two brand colors (within a tolerance of 0.1)
# and paint the near-black as true black. Every other color keeps what the
# tracer found; drop both tolerances to snap everything onto the two.
curl -X POST https://api.justvectorize.com/api/v1/vectorize \
  -H "Authorization: Bearer $JUSTVECTORIZE_API_KEY" \
  -F "file=@logo.png" \
  -F 'palette=[{"color":"#1a1a1a","remapped":"#000000","tolerance":0.1},{"color":"#ff5c00","tolerance":0.1}]' \
  | jq -r .fileUrl

Each detected color snaps to the nearest entry whose tolerance reaches it, and a tie goes to the entry listed first. Because the default tolerance matches everything, a list of plain colors is a hard snap: the output carries no color you did not list, which makes palette the reliable way to hold a brand palette across a whole batch. Small tolerances only clean up near-matches and leave every other color alone. Two exceptions to the hard snap: draw_style=fill_gradients brings in ramp colors from outside the palette, and an empty list is ignored.

Parameter reference

Every field below is optional and is sent as a string form field. The defaults are what you get when the field is absent; the order of the groups is the order the pipeline runs in, from the pixels going in to the file coming out.

Errors

Failures come back as JSON with an error string. The status code is what you should branch on:

const res = await fetch("https://api.justvectorize.com/api/v1/vectorize", { method: "POST", headers, body });

if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: res.statusText }));
  throw new Error(`${res.status}: ${error}`);
}

const { fileUrl } = await res.json();

Limits and billing

• One credit per production image. A preview costs 0.2 credits, a test costs nothing, and so does a request that fails — see Pricing.
• Credits roll over up to 5× your monthly allowance, so a plan sized around an average month absorbs a busy one.
• Integration is free. Build and test against the API with image_mode=test and no subscription — credits are what you pay for when you start shipping production results.
• Input is downsampled to 2048 px on its longest side and to max_pixels in area, so an enormous source image costs the same as a sensible one and traces no slower.

Plans and prices are on the pricing page. Anything the docs do not answer, ask us on the contact page or at contact@justvectorize.com.