pixelvault

Official Python SDK for PixelVault, agent-first image hosting. Sync and asyncio clients on top of httpx. Python 3.9+.

pip install pixelvault

Quick start

from pixelvault import PixelVault

pv = PixelVault()  # reads PIXELVAULT_API_KEY, or pass api_key="pv_live_..."

# A path, bytes or a binary file object
image = pv.images.upload("screenshot.png")
print(image["url"])  # https://img.pixelvault.dev/...

# Import from a URL, auto-delete after one hour
pv.images.upload(url="https://example.com/a.png", expires_in=3600)

With no API key at all, images.upload(file) makes an anonymous upload that expires after 30 days.

Generate an image from a prompt and host it in one call (spends monthly credits, see the table below):

image = pv.images.generate("flat vector hero, a robot at a laptop, no text")
print(image["url"])         # https://img.pixelvault.dev/...
print(image["generation"])  # {'model': 'flux-1-schnell', 'credits_charged': 1, 'credits_remaining': 9}

Asyncio:

from pixelvault import AsyncPixelVault

async with AsyncPixelVault() as pv:
    image = await pv.images.upload("screenshot.png")
    async for img in pv.images.list_all():
        print(img["id"])

API

Errors and retries

Every failure raises PixelVaultError with .status (0 for network errors), .code (for example upload_limit_reached) and .retry_after (seconds, when sent).

from pixelvault import PixelVault, PixelVaultError

try:
    pv.images.upload("big.png")
except PixelVaultError as err:
    if err.code == "upload_limit_reached":
        print(err.message)  # links to the pricing page

The client retries 429 (honoring Retry-After up to 30 seconds) and, for GET/DELETE only, 5xx and network errors. Uploads and images.generate are never retried after a 5xx or a network error, so a lost response cannot create a duplicate image or spend credits twice. Tune with max_retries (default 2) and timeout (seconds, default 60).

License

MIT