image-studio-sdk 1.0.0

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

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.

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, what they do, and their parameters at runtime:

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 — full SDK reference
• docs/examples.md — end-to-end examples
• Interactive API docs: https://studio.ross-developers.com/v1/docs

Development

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.