Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

Serve media from your own domain

Last updated: November 2026

Attach a hostname such as media.example.com to one project. PixelVault keeps storage and delivery unchanged, but public URLs become https://media.example.com/<asset_id>.<ext>. Starter includes 1 custom domain per account; Pro includes 3.

1. Add the hostname

Use a secret API key from the project the hostname should serve. The account email must be verified.

curl -X POST https://api.pixelvault.dev/v1/custom-domains \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"media.example.com"}'

The response contains the domain id, its current hostname and certificate statuses, and the authoritative cname_target. You can also add it from Dashboard → Settings → Custom domains.

2. Create the CNAME

At the DNS provider for your domain, create this record. Use DNS-only or unproxied mode during setup when your provider offers a proxy toggle.

Type    Name                 Target
CNAME   media.example.com    custom.pvcdn.dev

Use the exact target returned by the API rather than copying this example. Some hostnames also receive an ownership_verification TXT record; create it when present.

3. Wait for HTTPS

DNS propagation and certificate issuance are separate. The hostname is ready only when both hostname_status and certificate_status are active, making ready true.

curl -X POST https://api.pixelvault.dev/v1/custom-domains/dom_abc123/refresh \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

Do not treat a successful TLS handshake alone as readiness: another matching certificate may answer before the custom-hostname certificate finishes provisioning.

4. Use the custom URL

Canonical URLCustom-domain URL
img.pixelvault.dev/proj_abc/img_123.jpgmedia.example.com/img_123.jpg
img.pixelvault.dev/proj_abc/blog/img_123.jpgmedia.example.com/blog/img_123.jpg

Every media response keeps the canonical url and includes branded_url when a custom domain is ready. Use that returned value rather than rebuilding a URL yourself; private signatures and image transform query parameters are preserved. The CLI can manage the domain and select the branded result:

pixelvault domains add media.example.com
# Add the returned DNS records, then refresh until ready=true
pixelvault domains refresh dom_abc123
# Print the branded URL when ready; falls back to the canonical URL
pixelvault upload photo.jpg --branded

Remove a hostname

Delete the custom domain in PixelVault first. Routing stops immediately and Cloudflare removes its certificate. Then remove the customer DNS record. A project cannot be deleted while it still has custom domains.

API operations