<!-- Markdown twin of https://pixelvault.dev/docs/private-media/ -->

# 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](/docs/api/images/#upload_image)

`visibility=private` form field (or JSON field on URL import)

[Batch](/docs/api/images/#batch_upload)

`collection.visibility: "private"`

[Video](/docs/api/videos/#upload_video), [audio](/docs/api/audio/#upload_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](/docs/transforms/) 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`](/docs/api/images/#sign_image_url)

`url`, `expires`

[`POST /v1/videos/:id/sign-url`](/docs/api/videos/#sign_video_url)

The original `url`, `poster_url`, `social_url`, and every existing enrichment artifact, all with one `expires`

[`POST /v1/audio/:id/sign-url`](/docs/api/audio/#sign_audio_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`](/docs/lifecycle/).

## 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](/pricing/); retrying won't help.

## Next steps

-   [Share private media with signed URLs](/docs/guides/signed-urls/): a runnable server example.
-   [Private CI screenshots](/docs/guides/ci-screenshots/) on pull requests.
-   [Expiry & retention](/docs/lifecycle/).
