Metadata-Version: 2.5
Name: justvectorize
Version: 0.1.0
Summary: Vectorize images: turn PNG, JPG and WebP into SVG, PDF, EPS, AI or DXF with the JustVectorize API. Library and CLI.
Project-URL: Homepage, https://www.justvectorize.com
Project-URL: Documentation, https://www.justvectorize.com/docs
Project-URL: Pricing, https://www.justvectorize.com/pricing
Author-email: Algora Ventures Limited <contact@justvectorize.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bitmap-to-vector,dxf,eps,image-trace,jpg-to-svg,justvectorize,png-to-svg,potrace,svg,vectorize,vectorizer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: typing-extensions>=4.6
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# justvectorize

Vectorize images from Python or the command line. Turn PNG, JPG and WebP into **SVG, PDF, EPS, AI or DXF** with the [JustVectorize](https://www.justvectorize.com) 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](https://www.justvectorize.com/account).
2. Open the **API keys** panel and create a key.
3. Put it in an environment variable:

```sh
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](https://www.justvectorize.com/pricing).

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

## 2. Install

```sh
pip install justvectorize
```

Requires Python 3.10 or newer.

## 3. Vectorize

```python
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

| Method | Returns |
| --- | --- |
| `vectorize(image, **options)` | `VectorizeResult`: `file_url` (a temporary download link, about 30 days), `operation_id`, `format` |
| `vectorize_to_bytes(image, **options)` | `VectorizeFileResult`: the above plus `data` (bytes) and `content_type` |
| `vectorize_to_string(image, **options)` | the file as text, e.g. SVG markup |
| `vectorize_to_file(image, out_path, **options)` | writes the file (creating folders), returns the result with `path` |

`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:

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

### Examples

```python
# 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](https://www.justvectorize.com/docs#parameters).

### Async

```python
from justvectorize import AsyncJustVectorize

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

### Client options

```python
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`:

```python
from justvectorize import JustVectorizeError

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

| Status | Meaning |
| --- | --- |
| 400 | No file, not an image, or bad palette JSON |
| 401 | Missing, invalid or revoked API key |
| 402 | Out of API credits |
| 413 | Image over 20 MB |
| 422 | An option is the wrong type, out of range or unknown |
| 429 / 5xx | Retried automatically, then raised |

Failed requests are not charged.

## CLI

```sh
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](https://www.justvectorize.com/docs)
- [Pricing](https://www.justvectorize.com/pricing)
- Node.js: [`@algora-ventures/justvectorize`](https://www.npmjs.com/package/@algora-ventures/justvectorize)
- Support: contact@justvectorize.com

MIT © Algora Ventures Limited
