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:
| Upload | How |
|---|---|
| Image | visibility=private form field (or JSON field on URL import) |
| Batch | collection.visibility: "private" |
| Video, audio | X-PixelVault-Visibility: private header on direct uploads, visibility JSON field on URL imports |
| Generated / edited images | visibility 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 } } | Endpoint | Returns |
|---|---|
POST /v1/images/:id/sign-url | url, expires |
POST /v1/videos/:id/sign-url | The original url, poster_url, social_url, and every existing enrichment artifact, all with one expires |
POST /v1/audio/:id/sign-url | The 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
- Share private media with signed URLs: a runnable server example.
- Private CI screenshots on pull requests.
- Expiry & retention.