Metadata-Version: 2.4
Name: vectosolve
Version: 1.0.0
Summary: Official Python SDK for the VectoSolve API — AI-powered image vectorization, background removal, upscaling, and SVG generation.
Project-URL: Homepage, https://vectosolve.com
Project-URL: Documentation, https://vectosolve.com/developers
Project-URL: Repository, https://github.com/vectosolve/vectosolve-python
Project-URL: Changelog, https://github.com/vectosolve/vectosolve-python/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/vectosolve/vectosolve-python/issues
Author-email: VectoSolve <support@vectosolve.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,background-removal,cricut,embroidery,image-processing,image-to-svg,laser-cutting,raster-to-vector,silhouette,svg,upscale,vector,vectorize
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx<1.0.0,>=0.24.0
Description-Content-Type: text/markdown

# VectoSolve Python SDK

Official Python client for the [VectoSolve API](https://vectosolve.com/developers) — AI-powered image vectorization, background removal, upscaling, and SVG generation.

[![PyPI](https://img.shields.io/pypi/v/vectosolve)](https://pypi.org/project/vectosolve/)
[![Python](https://img.shields.io/pypi/pyversions/vectosolve)](https://pypi.org/project/vectosolve/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install vectosolve
```

## Quick Start

```python
from vectosolve import VectoSolve

client = VectoSolve(api_key="vs_your_api_key")

# Convert an image to SVG
result = client.vectorize("photo.png")
result.save("output.svg")
print(f"Credits remaining: {result.credits.remaining}")
```

Get your API key at [vectosolve.com/dashboard](https://vectosolve.com/dashboard).

## Features

| Method | Description | Cost |
|--------|-------------|------|
| `vectorize()` | Convert raster images (PNG, JPG, WebP) to clean SVG | $0.20 |
| `remove_background()` | Remove image backgrounds with AI | $0.07 |
| `upscale()` | AI-powered image upscaling (2x/4x) | $0.15 |
| `generate_svg()` | Generate SVGs from text prompts | $0.25 |
| `generate_logo()` | AI logo generation with multiple variants | $0.25-$0.40 |
| `generate_pattern()` | Generate seamless tileable patterns | $0.25 |
| `batch()` | Process up to 10 images in a single request | varies |

## Usage

### Vectorize (Image to SVG)

```python
# From a local file
result = client.vectorize("photo.png")
result.save("output.svg")

# From a URL
result = client.vectorize("https://example.com/image.png")
print(result.svg)  # Raw SVG string
```

### Remove Background

```python
result = client.remove_background("product.jpg")
print(result.image_url)  # URL of the processed image
```

### Upscale

```python
result = client.upscale("small-image.png")
print(result.image_url)
```

### Generate SVG from Text

```python
result = client.generate_svg(
    "a golden retriever playing fetch in a park",
    style="vector_illustration",
    size="1024x1024",
    colors=["#f4a460", "#228b22", "#87ceeb"],
)
result.save("dog.svg")
```

**Available styles:** `vector_illustration`, `vector_illustration/line_art`, `vector_illustration/engraving`, `vector_illustration/linocut`, `vector_illustration/bold_stroke`, `vector_illustration/colored_stencil`, `vector_illustration/thin`, `vector_illustration/mosaic`, `vector_illustration/flat_2`

**Available sizes:** `1024x1024`, `1024x1536`, `1536x1024`

### Generate Logo

```python
result = client.generate_logo(
    "minimalist coffee shop logo with a steaming cup",
    model="v3",
    num_variants=4,
    colors=["#6f4e37", "#f5f5dc"],
)

for i, logo in enumerate(result.logos):
    logo.save(f"logo_{i}.svg")
```

### Generate Pattern

```python
result = client.generate_pattern(
    "tropical leaves and flowers",
    colors=["#2d5016", "#ff6b6b", "#ffd93d"],
)
print(result.image_url)
```

### Batch Processing

```python
result = client.batch([
    {"url": "https://example.com/photo1.png", "operation": "vectorize"},
    {"url": "https://example.com/photo2.jpg", "operation": "remove_bg"},
    {"url": "https://example.com/photo3.png", "operation": "upscale"},
])

for item in result.results:
    if item.success:
        print(f"[{item.index}] {item.operation}: {item.url}")
    else:
        print(f"[{item.index}] Failed: {item.error}")

print(f"Processed: {result.total_processed}, Failed: {result.total_failed}")
```

## Environment Variable

Instead of passing the API key directly, you can set it as an environment variable:

```bash
export VECTOSOLVE_API_KEY="vs_your_api_key"
```

```python
client = VectoSolve()  # Automatically reads VECTOSOLVE_API_KEY
```

## Error Handling

```python
from vectosolve import (
    VectoSolve,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    ValidationError,
)

client = VectoSolve(api_key="vs_your_api_key")

try:
    result = client.vectorize("image.png")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError as e:
    print(f"Need {e.required} credits — top up at vectosolve.com/pricing")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Bad request: {e.message}")
```

## Context Manager

```python
with VectoSolve(api_key="vs_your_api_key") as client:
    result = client.vectorize("photo.png")
    result.save("output.svg")
# Connection automatically closed
```

## Use Cases

- **Cricut & Silhouette** — Convert designs to cut-ready SVGs
- **Laser cutting** — Vectorize artwork for laser engravers
- **Embroidery** — Convert images for embroidery machines
- **E-commerce** — Remove backgrounds from product photos
- **Design automation** — Generate logos and patterns programmatically

## Links

- [API Documentation](https://vectosolve.com/developers)
- [Dashboard & API Keys](https://vectosolve.com/dashboard)
- [Pricing](https://vectosolve.com/pricing)
- [GitHub](https://github.com/vectosolve/vectosolve-python)

## License

MIT
