Official Python SDK for PixelVault, agent-first media hosting.
Sync and asyncio clients on top of httpx. Python 3.9+.
pip install pixelvaultfrom 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"])| 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.
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 pageThe 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).
MIT