Metadata-Version: 2.4
Name: image-studio-sdk
Version: 1.0.0
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

# image-studio-sdk — the Image Studio Python SDK

**Official Python client for `https://studio.ross-developers.com/v1`** — an
async-job REST API serving 13 image-generation and image-editing diffusion
models.

This package is a pure client SDK: it talks to the hosted API and nothing
else. Dependencies are `httpx` + `Pillow` — no torch, no model downloads,
no server code.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)]()
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)]()

## 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")
```

Image editing:

```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")
```

Async submit + poll (long jobs):

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

Discover models, what they do, and their parameters at runtime:

```python
with ImageStudio() as studio:
    # Every task the API offers — fine-grained (structure-control,
    # local-redrawing, super-resolution, …), each with a description,
    # its endpoint, and the models that serve it:
    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))
```

## 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 to `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.

## Documentation

- [docs/client.md](docs/client.md) — full SDK reference
- [docs/examples.md](docs/examples.md) — end-to-end examples
- Interactive API docs: `https://studio.ross-developers.com/v1/docs`

## Development

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

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