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

Organize media

Goal: find media again by what it belongs to (a build, a customer, a blog post) instead of keeping your own index of IDs. PixelVault has three tools: folders, custom metadata, and collections.

Folders

A folder is a path segment in the CDN URL and a label on the asset. Set it at upload: the folder form or JSON field for images, X-PixelVault-Folder (direct) or folder (URL import, resumable initiation) for video and audio. Private images ignore the folder because they live under a reserved private prefix. Video and audio lists filter on it (?folder=agents); move a video or audio asset with PATCH. When you watermark with tile, prefix the image path with its folder.

Custom metadata

Attach a JSON object (up to 50 top-level keys, 4 KB) at upload, replace it later with PATCH and {"metadata": {...}} (null clears it), and find assets again with ?metadata={"env":"prod"} or ?meta[env]=prod. All pairs must match. It is returned as metadata on every asset. Don't store secrets in it.

Metadata
# attach metadata at upload (a JSON string in multipart)
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -F "file=@hero.png" \
  -F 'metadata={"env":"prod","post":"launch"}'

# find it again: all pairs must match
curl -G https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  --data-urlencode "meta[env]=prod" \
  --data-urlencode "meta[post]=launch"

# replace it later (null clears it)
curl -X PATCH https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"env": "staging"}}'
  • Metadata is applied to new images only: when dedupe or an Idempotency-Key replay returns an existing image, the metadata you sent is ignored (change it with PATCH).
  • It is ignored on keyless uploads, and batch items with invalid metadata fail individually with invalid_metadata.
  • Video and audio take it as the X-PixelVault-Metadata header on direct uploads, or the metadata JSON field on URL imports. Reference: images, videos, audio.
curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: video/mp4" \
  -H "X-PixelVault-Filename: run-42.mp4" \
  -H "X-PixelVault-Folder: agents" \
  -H 'X-PixelVault-Metadata: {"run":"42"}' \
  --data-binary @run-42.mp4

curl "https://api.pixelvault.dev/v1/videos?folder=agents&meta[run]=42" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

Collections

A collection is a typed group of media assets (a CI run, a generation set, an album) with shared metadata and its own lifecycle. The batch endpoint creates or reuses one per (type, name); video and audio join an existing same-visibility collection with collection_id (or X-PixelVault-Collection-Id) at upload or via PATCH.

GET  /v1/collections?type=ci_build&name=run-123   # list your collections
GET  /v1/collections/:id                         # a collection and its media assets
GET  /v1/images?collection_id=col_…              # filter any media list by collection
POST /v1/collections/:id/close                   # close it and apply its cleanup policy
  • GET /v1/collections lists your collections, filtered by type and name.
  • GET /v1/collections/:id returns the collection and an assets array with every member; images remains as the backward-compatible image-only subset.
  • GET /v1/images?collection_id=…, /v1/videos?collection_id=…, or /v1/audio?collection_id=… filter by collection.
  • POST /v1/collections/:id/close closes a collection and applies its cleanup policy: a closed ci_build collection's members are removed at the next sweep.

Next steps