Metadata-Version: 2.4
Name: image-studio-sdk
Version: 1.0.1
Summary: Python client SDK for the Ross Image Studio API (studio.ross-developers.com/v1).
Author: Andre Ross
License-Expression: Apache-2.0
Project-URL: Homepage, https://studio.ross-developers.com
Project-URL: Documentation, https://studio.ross-developers.com/v1/docs
Keywords: image-generation,image-editing,diffusion,text-to-image,sdk,api-client,ross-image-studio
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: Pillow>=10.0
Dynamic: license-file

<div align="center">

# 🎨 Image Studio Python SDK

**Official Python client for the [Ross Image Studio API](https://studio.ross-developers.com) — 13 image-generation & image-editing diffusion models behind one async-job REST API.**

[![PyPI version](https://img.shields.io/pypi/v/image-studio-sdk.svg?color=blue)](https://pypi.org/project/image-studio-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/image-studio-sdk.svg)](https://pypi.org/project/image-studio-sdk/)
[![License](https://img.shields.io/pypi/l/image-studio-sdk.svg?color=green)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/image-studio-sdk.svg?color=orange)](https://pypi.org/project/image-studio-sdk/)
[![Typed](https://img.shields.io/badge/typed-py.typed-3776AB.svg)](https://peps.python.org/pep-0561/)

<a href="https://pypi.org/project/image-studio-sdk/"><b>PyPI</b></a> ·
<a href="https://studio.ross-developers.com/v1/docs"><b>API Docs</b></a> ·
<a href="https://studio.ross-developers.com"><b>Homepage</b></a>

</div>

---

`image-studio-sdk` is a **pure client SDK**: it talks to the hosted Image Studio API and nothing else. Its only dependencies are [`httpx`](https://www.python-httpx.org/) + [`Pillow`](https://python-pillow.org/) — no torch, no model downloads, no server code.

## ✨ Features

- 🖼️ **Generate & edit** — text-to-image and image editing across 13 diffusion models
- ⏳ **Async jobs done right** — `submit → poll → download`; never holds a long HTTP read open
- 🔁 **Safe retries** — automatic, replay-safe retries plus an auto `Idempotency-Key` so a retry never double-charges a GPU job
- 🧩 **Typed end to end** — frozen dataclasses, a `py.typed` marker, and a full typed error hierarchy
- 🪶 **Featherweight** — two runtime dependencies (`httpx`, `Pillow`)

## 📦 Install

```bash
pip install image-studio-sdk
export IMAGE_STUDIO_API_KEY=isk_...   # issued per client
```

## 🚀 Quick start

```python
from image_studio import ImageStudio

with ImageStudio() as studio:
    job = studio.generate("irie", "a fluffy orange cat in aviator goggles", seed=42)
    studio.download(job.images[0], "cat.png")
```

<details>
<summary><b>Image editing</b></summary>

```python
with ImageStudio() as studio:
    job = studio.edit("bashment", "add a rainbow to the sky", image="photo.jpg")
    studio.download(job.images[0], "photo_rainbow.png")
```
</details>

<details>
<summary><b>Async submit + poll (long jobs)</b></summary>

```python
with ImageStudio() as studio:
    handle = studio.submit("biggup", "a detailed cityscape", image="city.png")
    print(handle.job.id, handle.job.status)          # job_..., queued
    job = handle.result(timeout=600)                 # polls until terminal
```
</details>

<details>
<summary><b>Discover models & tasks at runtime</b></summary>

```python
with ImageStudio() as studio:
    # Every task the API offers — structure-control, local-redrawing, super-resolution, …
    for t in studio.tasks():
        print(t.id, "->", t.endpoint, t.models)
        print("   ", t.description)

    # Each model carries its task id and the endpoint that takes it:
    for m in studio.models():
        print(m.id, m.task, m.endpoint, sorted(m.parameters))
```
</details>

## ⚙️ Configuration

| Environment variable | Purpose | Default |
|---|---|---|
| `IMAGE_STUDIO_API_KEY` | Bearer token (**required**) | — |
| `IMAGE_STUDIO_BASE_URL` | API root | `https://studio.ross-developers.com/v1` |

Both can also be passed directly: `ImageStudio(api_key=..., base_url=...)`.

## 🧨 Errors

All failures raise typed exceptions from `image_studio`:
`AuthenticationError`, `ValidationError`, `RateLimitError` (queue full — carries `retry_after`),
`JobFailedError`, `JobCanceledError`, `PollTimeoutError`, and friends. Submits send an automatic
`Idempotency-Key`, so retrying a failed submit never double-charges a job.

```python
from image_studio.client import JobFailedError, ValidationError

try:
    job = studio.generate("roots", "portrait", age=500)
except ValidationError as e:
    print(e.param, e.code)          # "age", "invalid_parameter"
except JobFailedError as e:
    print(e.job.id, e.code)         # inspect and resubmit
```

## 📚 Documentation

- **Full SDK reference & examples ship with the package** — `docs/client.md` and `docs/examples.md` are
  bundled in the [source distribution](https://pypi.org/project/image-studio-sdk/#files).
- **Interactive API docs:** <https://studio.ross-developers.com/v1/docs>
- **Homepage:** <https://studio.ross-developers.com>

## 🛠️ Development

```bash
pip install -e . pytest
python -m pytest tests/ -q        # offline — httpx.MockTransport, no server needed
python -m build                   # → dist/image_studio_sdk-<version>-py3-none-any.whl
```

The server/API implementation lives in the separate `image-studio-server-api-python` repository.

## 📄 License

[Apache-2.0](LICENSE) © Andre Ross
