Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ 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/...
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)
Expand Down Expand Up @@ -98,6 +98,7 @@ async with AsyncPixelVault() as pv:
| `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 |

Expand All @@ -110,6 +111,8 @@ 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
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "pixelvault"
version = "0.7.0"
version = "0.8.0"
description = "Official Python SDK for PixelVault, agent-first media hosting"
readme = "README.md"
license = "MIT"
Expand Down
2 changes: 1 addition & 1 deletion src/pixelvault/_core.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

from .errors import PixelVaultError

__version__ = "0.7.0"
__version__ = "0.8.0"

DEFAULT_BASE_URL = "https://api.pixelvault.dev"
MAX_BACKOFF = 30.0
Expand Down
3 changes: 3 additions & 0 deletions src/pixelvault/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
from .videos import AsyncVideos, Videos
from .audio import AsyncAudioFiles, AudioFiles
from .exports import AsyncExports, Exports
from .custom_domains import AsyncCustomDomains, CustomDomains
from .types import (
ApiKey,
CreatedKey,
Expand Down Expand Up @@ -92,6 +93,7 @@ def __init__(
self.audio = AudioFiles(self)
self.usage = _Usage(self)
self.keys = _Keys(self)
self.custom_domains = CustomDomains(self)

def __enter__(self) -> "PixelVault":
return self
Expand Down Expand Up @@ -329,6 +331,7 @@ def __init__(
self.audio = AsyncAudioFiles(self)
self.usage = _AsyncUsage(self)
self.keys = _AsyncKeys(self)
self.custom_domains = AsyncCustomDomains(self)

async def __aenter__(self) -> "AsyncPixelVault":
return self
Expand Down
62 changes: 62 additions & 0 deletions src/pixelvault/custom_domains.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
from __future__ import annotations

from typing import Any, cast
from urllib.parse import quote

from ._core import Request
from .types import CustomDomain, CustomDomainList


def _seg(value: str) -> str:
return quote(value, safe="")


class CustomDomains:
def __init__(self, client: Any) -> None:
self._c = client

def list(self) -> CustomDomainList:
"""List domains on the active project and account-wide plan capacity."""
return cast(CustomDomainList, self._c._send(Request("GET", "/v1/custom-domains")))

def create(self, hostname: str) -> CustomDomain:
"""Attach a customer-owned hostname and return its required DNS records."""
body = self._c._send(Request("POST", "/v1/custom-domains", json={"hostname": hostname}))
return cast(CustomDomain, body["data"])

def refresh(self, domain_id: str) -> CustomDomain:
"""Re-check DNS and certificate state after records change."""
body = self._c._send(
Request("POST", f"/v1/custom-domains/{_seg(domain_id)}/refresh")
)
return cast(CustomDomain, body["data"])

def delete(self, domain_id: str) -> None:
"""Remove a custom domain. Canonical PixelVault URLs keep working."""
self._c._send(Request("DELETE", f"/v1/custom-domains/{_seg(domain_id)}"))


class AsyncCustomDomains:
def __init__(self, client: Any) -> None:
self._c = client

async def list(self) -> CustomDomainList:
return cast(
CustomDomainList,
await self._c._send(Request("GET", "/v1/custom-domains")),
)

async def create(self, hostname: str) -> CustomDomain:
body = await self._c._send(
Request("POST", "/v1/custom-domains", json={"hostname": hostname})
)
return cast(CustomDomain, body["data"])

async def refresh(self, domain_id: str) -> CustomDomain:
body = await self._c._send(
Request("POST", f"/v1/custom-domains/{_seg(domain_id)}/refresh")
)
return cast(CustomDomain, body["data"])

async def delete(self, domain_id: str) -> None:
await self._c._send(Request("DELETE", f"/v1/custom-domains/{_seg(domain_id)}"))
39 changes: 39 additions & 0 deletions src/pixelvault/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
class Image(TypedDict):
id: str
url: str
#: Same asset on the project's active custom domain, when configured and ready.
branded_url: NotRequired[str]
mime_type: str
size: int
width: Optional[int]
Expand Down Expand Up @@ -61,6 +63,7 @@ class ImagePage(TypedDict):

class SignedUrl(TypedDict):
url: str
branded_url: NotRequired[str]
expires: int


Expand Down Expand Up @@ -116,6 +119,38 @@ class Usage(TypedDict):
video_enrichment: NotRequired[VideoSecondsUsage]


class CustomDomainVerification(TypedDict):
type: Literal["TXT"]
name: str
value: str


class CustomDomain(TypedDict):
id: str
project_id: str
hostname: str
status: str
hostname_status: str
certificate_status: str
ready: bool
cname_target: str
ownership_verification: Optional[CustomDomainVerification]
created_at: str
updated_at: str


class CustomDomainCapacity(TypedDict):
limit: int
total: int
project_total: int
cname_target: str


class CustomDomainList(TypedDict):
data: List[CustomDomain]
meta: CustomDomainCapacity


class ApiKey(TypedDict):
id: str
type: str
Expand Down Expand Up @@ -157,6 +192,7 @@ class Video(TypedDict):
kind: str
url: str
original_url: str
branded_url: NotRequired[str]
visibility: str
mime_type: str
size: int
Expand Down Expand Up @@ -217,6 +253,7 @@ class Audio(TypedDict):
kind: Literal["audio"]
url: str
original_url: str
branded_url: NotRequired[str]
visibility: Literal["public", "private"]
mime_type: Literal["audio/mpeg", "audio/wav", "audio/mp4", "audio/ogg"]
size: int
Expand Down Expand Up @@ -244,6 +281,7 @@ class AudioPage(TypedDict):

class AudioSignedUrl(TypedDict):
url: str
branded_url: NotRequired[str]
original_url: str
expires: int
visibility: Literal["public", "private"]
Expand Down Expand Up @@ -314,6 +352,7 @@ class ExportWaitResult(TypedDict):

class VideoSignedUrls(TypedDict):
url: str
branded_url: NotRequired[str]
enrichment: Dict[str, Any]
expires: int
poster_url: NotRequired[str]
Expand Down
45 changes: 45 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -963,3 +963,48 @@ def handler(req):
started = await pv.exports.start()
result = await pv.exports.wait(started["job_id"], timeout=0)
assert result["job"]["status"] == "processing" and result["timed_out"] is True

def test_custom_domains_manage_encoded_ids_and_capacity():
seen = []
domain = {
"id": "dom/1",
"project_id": "proj_1",
"hostname": "media.example.com",
"status": "active",
"hostname_status": "active",
"certificate_status": "active",
"ready": True,
"cname_target": "custom.pvcdn.dev",
"ownership_verification": None,
"created_at": "2026-11-18T00:00:00Z",
"updated_at": "2026-11-18T00:00:00Z",
}

def handler(req):
seen.append(req)
if req.method == "GET":
return httpx.Response(
200,
json={
"data": [domain],
"meta": {
"limit": 1,
"total": 1,
"project_total": 1,
"cname_target": "custom.pvcdn.dev",
},
},
)
if req.method == "DELETE":
return httpx.Response(200, json={"data": {"id": "dom/1", "deleted": True}})
return httpx.Response(200, json={"data": domain})

domains = make(handler).custom_domains
assert domains.list()["meta"]["limit"] == 1
assert domains.create("media.example.com")["ready"] is True
assert domains.refresh("dom/1")["hostname"] == "media.example.com"
domains.delete("dom/1")

assert json.loads(seen[1].content) == {"hostname": "media.example.com"}
assert str(seen[2].url).endswith("/v1/custom-domains/dom%2F1/refresh")
assert str(seen[3].url).endswith("/v1/custom-domains/dom%2F1")
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading