justvectorize

Vectorize images from Python or the command line. Turn PNG, JPG and WebP into SVG, PDF, EPS, AI or DXF with the JustVectorize API.

• Sync and async clients, fully typed: your editor autocompletes every tracer option
• Every documented option: palettes, color limits, background removal, stroke styles for cutters and plotters, output sizing
• Automatic retries on rate limits and transient errors
• A CLI for one-off and batch conversions

1. Get an API key

The package calls the JustVectorize API, so you need a key:

1. Sign in at justvectorize.com/account.
2. Open the API keys panel and create a key.
3. Put it in an environment variable:

export JUSTVECTORIZE_API_KEY=jv_live_xxxxxxxxxxxxxxxxxxxxxxxx

One production trace costs one credit. image_mode="test" is free, so you can integrate before you subscribe. See pricing.

Keep the key server-side. It spends your credits. Use it from your backend or scripts, and never commit it.

2. Install

pip install justvectorize

Requires Python 3.10 or newer.

3. Vectorize

from justvectorize import JustVectorize

client = JustVectorize(api_key="jv_live_...")   # or JustVectorize() to read JUSTVECTORIZE_API_KEY

# Trace and save. The format comes from the extension.
client.vectorize_to_file("logo.png", "logo.svg", max_colors=4, remove_bg=True)

Methods

image can be a file path (str or Path), an http(s) URL, bytes, or a file opened in binary mode.

Every method also takes file_name= (the upload's name) and timeout= (seconds).

There's also a shorthand that reads the key from the environment:

from justvectorize import vectorize
print(vectorize("photo.jpg", format="pdf").file_url)

Examples

# Inline SVG markup
svg = client.vectorize_to_string(image_bytes, format="svg", n_colors=3)

# A laser / plotter cut file: one stroke per edge, real-world units
client.vectorize_to_file(
    "sketch.jpg", "sketch.dxf",
    draw_style="stroke_edges", dxf_units="mm", width=100, unit="mm",
)

# Lock output to brand colors
client.vectorize_to_file(
    "logo.png", "logo.pdf",
    palette=["#000000", {"color": "#ff5c00", "tolerance": 0.1}],
)

# Free test trace while you integrate
client.vectorize("logo.png", image_mode="test")

Options use the API's own names. The full list is in the parameter reference.

Async

from justvectorize import AsyncJustVectorize

async with AsyncJustVectorize() as client:
    await client.vectorize_to_file("logo.png", "logo.svg")

Client options

JustVectorize(
    api_key="jv_live_...",  # default: os.environ["JUSTVECTORIZE_API_KEY"]
    timeout=120.0,          # seconds per request
    max_retries=2,          # on 429, 5xx and network errors
    http_client=None,       # your own httpx.Client (proxies, custom transport)
)

Use it as a context manager (with JustVectorize() as client:) or call client.close() to release connections.

Errors

Failures raise JustVectorizeError with the HTTP status:

from justvectorize import JustVectorizeError

try:
    client.vectorize("logo.png")
except JustVectorizeError as error:
    if error.status == 402:
        ...  # out of credits

Failed requests are not charged.

CLI

justvectorize logo.png                                   # → logo.svg
justvectorize logo.png -o logo.pdf --max-colors 3 --remove-bg
justvectorize sketch.jpg -f dxf --draw-style stroke_edges --dxf-units mm
justvectorize *.png -o vectors/ --image-mode test        # batch, free
justvectorize logo.png --url                             # print the link only

The CLI reads JUSTVECTORIZE_API_KEY, or takes --api-key. It accepts any tracer option as --kebab-case or --snake_case. Run justvectorize --help to see them all. python -m justvectorize.cli works too.

Links

• API docs
• Pricing
• Node.js: @algora-ventures/justvectorize
• Support: contact@justvectorize.com

MIT © Algora Ventures Limited