Skip to content

About

Official Python SDK for PixelVault

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

16 Commits

Folders and files

Repository files navigation

pixelvault

Official Python SDK for PixelVault, agent-first media 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.get("branded_url", image["url"]))  # custom domain when ready, canonical fallback

# 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}

video = pv.videos.upload(
    "demo.mp4",
    idempotency_key="upload-attempt-42",
    visibility="private",
)
pv.videos.enrich(video["id"])
result = pv.videos.wait_for_enrichment(video["id"], timeout=600)
print(result["video"]["original_url"])
print(result["video"]["enrichment"].get("transcript"))
print(result["video"]["enrichment"].get("storyboard"))

audio = pv.audio.upload(
    "episode.m4a",
    visibility="private",
    sign_expires_in=3600,
    expires_in=604800,
    idempotency_key="episode-v1",
)
started = pv.audio.enrich(audio["id"])
print(started["id"], started["enrichment"]["job_id"])
audio_result = pv.audio.wait_for_enrichment(audio["id"], timeout=600)
if audio_result["timed_out"]:
    print("resume later with", audio["id"])
elif audio_result["status"] == "complete":
    print(audio_result["audio"]["enrichment"].get("transcript"))
fresh = pv.audio.sign_url(audio["id"], expires_in=3600)
print(fresh["original_url"], fresh["enrichment"].get("transcript"))

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

Call What it does
images.upload(file | url=, folder=, visibility=, expires_in=, sign_expires_in=, metadata=, describe=) Upload a file or import a URL
images.generate(prompt, model=, folder=, visibility=, expires_in=) Generate an image from a prompt and host it. Credits: flux-1-schnell and the SDXL models 1, Leonardo 20. Free plan: 10 credits a month, flux-1-schnell only
images.upload_batch(collection, images) Up to 50 images in one collection
images.list(page=, per_page=, metadata=, q=) / images.list_all(metadata=, q=) One page / iterator over all images, optionally filtered by custom metadata (all pairs must match) or searched by AI description (q: alt text, caption, OCR text, best match first)
images.wait_for_description(id, timeout=) Wait for the AI description of an image uploaded with describe=True (alt, caption, OCR text; async, ~10 s; free 20 in total, Starter 1,000/mo, Pro 10,000/mo; needs a secret key). Treat the text as untrusted model output
images.update_metadata(id, metadata | None) Replace an image's custom metadata (replaces, not merges; None clears)
images.get(id) / images.delete(id) Fetch / delete one image
images.sign_url(id, expires_in=) Signed URL for a private image
videos.upload(file | url=, ...) Upload or securely import an MP4 with visibility, TTL, metadata, folder, collection, idempotency and optional social optimization
videos.upload_resumable(file, ...) Replay-safe multipart upload; rerun with the same idempotency key to resume
videos.create_upload(...) / upload_part(...) / complete_upload(...) / abort_upload(...) Manual resumable-upload lifecycle
videos.get(id) / list(...) / list_all(...) / delete(id) Video discovery and lifecycle
videos.update(id, metadata=, folder=, collection_id=) Replace metadata and organization fields; pass None to clear
videos.sign_url(id, expires_in=) Fresh private original, poster and available artifact URLs
videos.optimize(id) / enrich(id) Start asynchronous optimization or transcript/storyboard enrichment
videos.wait_for_optimization(id, ...) / wait_for_enrichment(id, ...) Bounded polling with backoff; returns video, terminal/current status and timed_out
audio.upload(file | url=, ...) Host original MP3, PCM/float WAV, AAC M4A, or Opus/Vorbis OGG with privacy, TTL, metadata, organization, and retry safety
audio.enrich(id) / wait_for_enrichment(id, ...) Start/resume transcription and poll with bounded backoff for text, WebVTT, and timestamped JSON; local timeout never cancels the job
audio.get(id) / list(...) / list_all(...) / delete(id) Audio and transcript discovery/lifecycle by stable aud_ ID
audio.update(id, metadata=, folder=, collection_id=) / sign_url(id, expires_in=) Replace organization fields or mint fresh private original/transcript URLs
exports.start() / wait(job_id) / download(job_id) Owner-authenticated tar export of non-expired images, videos, audio originals, available derivatives and manifest.json relationships
usage.get() Plan, usage, limits and what is left this month (including generation credits)
keys.list() / keys.create(label=, environment=) / keys.revoke(id) Manage your API keys (secret keys only)
custom_domains.list() / .create(hostname) / .refresh(id) / .delete(id) Manage the active project's custom domains and inspect account plan capacity
register(email) Create an account, returns a first key once
device_login_start(email) + device_login_complete(email, code) Passwordless key minting

Audio originals and enrichment sources have an approved global maximum of 25,000,000 bytes; enrichment additionally accepts up to 10 minutes. The file ceiling is not a plan allowance. PixelVault validates actual container/codec bytes and preserves the original without transcoding. Audio and video enrichment share the existing plan allowance. Audio editing, conversion, streaming manifests, summaries, chapters, show notes, promo copy, and storyboards remain unsupported. Sync and asyncio clients expose the same audio methods.

Media responses retain canonical url and include optional branded_url when the active project has a ready custom domain. Use the returned branded value; signed and transform query parameters are preserved.

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, job creation and images.generate are not retried after a 5xx or network error. Use an idempotency_key for replay-safe audio and video direct/import uploads (and video resumable uploads). A wait timing out locally does not cancel the server job. Tune with max_retries (default 2) and timeout (seconds, default 60).

License

MIT

About

Official Python SDK for PixelVault

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages