image-studio-sdk 1.0.1

Python client SDK for the Ross Image Studio API (studio.ross-developers.com/v1).

🎨 Image Studio Python SDK

Official Python client for the Ross Image Studio API — 13 image-generation & image-editing diffusion models behind one async-job REST API.

PyPI · API Docs · Homepage

---

image-studio-sdk is a pure client SDK: it talks to the hosted Image Studio API and nothing else. Its only dependencies are httpx + Pillow — 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

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

🚀 Quick start

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

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)

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 & tasks at runtime

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

⚙️ 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.

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.
• Interactive API docs: https://studio.ross-developers.com/v1/docs
• Homepage: https://studio.ross-developers.com

🛠️ Development

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 © Andre Ross