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

Private media & signed URLs

Private images, MP4 videos, and audio are served behind HMAC-signed URLs: the link works while the signature is valid, but strip the token or let it expire and the CDN returns 403. Use private media for anything you wouldn't put on a public, crawlable CDN: CI screenshots of internal UI, user uploads, generated drafts.

Make an asset private

Visibility is chosen at upload and returned as visibility on every asset:

UploadHow
Imagevisibility=private form field (or JSON field on URL import)
Batchcollection.visibility: "private"
Video, audioX-PixelVault-Visibility: private header on direct uploads, visibility JSON field on URL imports
Generated / edited imagesvisibility in the request body (edits default to the source image's visibility)

Private uploads return a signed url plus signed_expires (Unix seconds). Set the link lifetime with sign_expires_in (or X-PixelVault-Sign-Expires-In on direct video/audio uploads); batch links default to 7 days, everything else to 1 hour. Publishable keys cannot create private media (403 private_forbidden).

How signed URLs work

https://img.pixelvault.dev/proj_xyz789/cp/i/img_abc123.png?token=Xr3…&expires=1795449600

A signed URL is the asset's CDN URL plus two query parameters: expires (Unix seconds) and token, an HMAC-SHA256 over the storage path and expiry. The serve edge checks both without a database call. A missing, altered, or expired signature returns 403. The signature binds the exact path, so transform parameters can't be added to a private URL (that also returns 403).

A signed URL is a bearer link: anyone holding it can view the asset until it expires. Mint short-lived links for the person or tool that needs them, and don't store them as permanent references; store the asset id instead.

Mint a fresh link

Signing never changes the asset: mint as many links as you need, each with its own lifetime. Body: { "expires_in": 3600 }, 60–2,592,000 seconds (30 days), default 1 hour; anything else is 400 invalid_expires_in.

curl -X POST https://api.pixelvault.dev/v1/images/img_abc123/sign-url \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'

→ { "data": { "url": "https://img.pixelvault.dev/…?token=…&expires=1795449600", "expires": 1795449600 } }
EndpointReturns
POST /v1/images/:id/sign-urlurl, expires
POST /v1/videos/:id/sign-urlThe original url, poster_url, social_url, and every existing enrichment artifact, all with one expires
POST /v1/audio/:id/sign-urlThe original plus only the transcript artifacts that exist, with one expires

Private video and audio artifacts (posters, social-ready copies, transcripts, storyboards) inherit the parent's visibility and share one expiry with the original, so a player never ends up with a live video and a dead caption track. Webhook payloads for private media carry links signed for 7 days and a refresh_url to mint new ones.

Revoke access

Links cannot be revoked one by one; they expire. Deleting the asset revokes every URL immediately and removes its derivatives. Signed-link expiry (sign_expires_in) only ends a link and never deletes bytes; to delete the asset itself on a schedule, use expires_in.

Plan limits

The free plan includes up to 100 private assets per project, counting images, videos and audio together; paid plans are unlimited. Past the cap, private uploads return 402 private_limit_reached (per item in a batch). Delete some private media or upgrade; retrying won't help.

Next steps