Metadata-Version: 2.4
Name: snapedit-api
Version: 1.0.0
Summary: Official Python SDK for the SnapEdit API — 40+ AI image & video editing models through a single API key.
Project-URL: Homepage, https://github.com/duonglm21/snapedit-api
Project-URL: Documentation, https://developer.snapedit.app
Project-URL: Repository, https://github.com/duonglm21/snapedit-api
Project-URL: Issues, https://github.com/duonglm21/snapedit-api/issues
Author-email: SnapEdit <developer@snapedit.app>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,background-removal,image-editing,image-generation,object-removal,snapedit,upscale,video-enhance,virtual-try-on
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx<1,>=0.23
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# SnapEdit Python SDK

Official Python SDK for the [SnapEdit API](https://developer.snapedit.app) — 40+ AI image & video editing models through a single API key. Sync and async, fully typed.

## Install

```bash
pip install snapedit-api
```

Requires Python 3.8+.

## Quick start

```python
from snapedit import SnapEdit

client = SnapEdit(api_key="sk-snap-...")  # or set SNAPEDIT_API_KEY

out = client.remove.background("https://example.com/photo.jpg")
print(out.data[0].url)
```

Inputs accept a **URL** (fetched server-side), a **local file path**, `bytes`, a `pathlib.Path`, or any binary file-like object:

```python
client.enhance.image("./portrait.jpg", zoom_factor=4, enhance_faces=True)

with open("photo.png", "rb") as f:
    client.remove.background(f)
```

## Async

```python
import asyncio
from snapedit import AsyncSnapEdit

async def main():
    async with AsyncSnapEdit() as client:  # reads SNAPEDIT_API_KEY
        out = await client.generate.zimage("a red panda astronaut", aspect_ratio="16:9")
        print(out.data[0].url)

asyncio.run(main())
```

## What's available

| Group | Methods (examples) |
|-------|--------------------|
| `client.detect` | `objects`, `text`, `wires` |
| `client.remove` | `background`, `objects`, `text`, `logo`, `wires`, `reflection`, `mirror`, `background_graphic` |
| `client.enhance` | `image`, `image_pro`, `art`, `restore`, `colorize`, `light_restore`, `backlit_fix`, `night_flash` |
| `client.generate` | `zimage`, `qwen`, `art`, `background`, `headshot`, `sticker` |
| `client.edit` | `edit`, `multi` |
| `client.beauty` | `retouch_skin`, `makeup`, `hairstyle` |
| `client.utility` | `outpaint`, `pose_suggest`, `ai_detect` |
| `client.try_on` | `create`, `get`, `cancel`, `wait`, `run` (async task) |
| `client.video` | `enhance`, `remove_logo` (upload-based async task) |
| `client.files` | `remove_logo_pdf` (upload-based async task) |

## Async task endpoints

Virtual try-on, video, and PDF endpoints are long-running. Use the one-shot
`run` / `enhance` / `remove_logo` helpers to submit and poll to completion:

```python
task = client.try_on.run(
    model_image="https://example.com/model.jpg",
    cloth_image="https://example.com/shirt.jpg",
    cloth_type="upper",
)
print(task.download_url)

# Videos upload the file for you, then poll:
result = client.video.enhance("./clip.mp4", zoom_factor="2K")
print(result.download_url)
```

Control polling with `WaitOptions`:

```python
from snapedit import WaitOptions

task = client.try_on.run(
    model_image="...", cloth_image="...", cloth_type="upper",
    opts=WaitOptions(poll_interval=2, max_wait=600,
                     on_progress=lambda t: print(t.status, t.progress)),
)
```

## Configuration

```python
client = SnapEdit(
    api_key="sk-snap-...",
    auth_scheme="bearer",   # or "api-key" header
    timeout=60.0,           # per-request seconds
    max_retries=2,          # auto-retry 429 / 5xx / network errors
    base_url="https://api.snapedit.app",
)
```

## Errors

```python
from snapedit import SnapEditError, SnapEditTaskError

try:
    client.remove.background("bad-input")
except SnapEditError as e:
    print(e.status, e.type, e.code)
    if e.is_rate_limit:
        print("retry after", e.retry_after, "seconds")
```

`SnapEditTaskError` is raised when an async task fails or a `wait()` times out.

## Rate limits

After any request, inspect `client.rate_limit` (`limit`, `remaining`, `reset`).

## License

MIT
