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

Upload images & PDFs

Goal: turn a local file or a remote URL into a permanent CDN URL you can embed anywhere. Prefer a browser? Use the free image-to-URL or PDF-to-URL tools.

Upload a file

Send multipart/form-data with a file field to POST /v1/images:

Upload
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -F "file=@screenshot.png" \
  -F "folder=docs"

The response (201) carries the image id, its CDN url, mime_type, size, and width/height when the file header has them. The URL is live immediately.

  • Formats: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF. Images return kind: "image". Max size per image is 5/10/15 MB on Free/Starter/Pro (limits).
  • PDFs return kind: "document", always download with Content-Disposition: attachment, are marked noindex, and reject image transform parameters.
  • Optimized URL: keyed public uploads of raster images (not SVG, GIF or private) also return optimized_url: the same image served as WebP or AVIF, chosen per browser, at quality 85 (url plus ?fmt=auto&q=85). It is usually much smaller. The original at url is never changed, so use whichever suits the embed. Any other size or format is a transform URL away.
  • Optional fields: folder and metadata (organize), visibility=private (signed URLs), expires_in (auto-delete), describe=true (AI alt text and tags), dedupe=true (reuse an identical existing image).
  • Retries: send an Idempotency-Key header so a retry after a timeout returns the original image instead of storing a second copy. See Idempotency.

Without an API key

Multipart uploads work without an API key — no account needed for your first upload. Keyless uploads are temporary ("temporary": true, expire in 30 days) and ignore metadata and idempotency keys. For a managed image or PDF without that fixed expiration, re-upload with an Authorization: Bearer key and use the new URL. The original anonymous URL still expires; free-plan retention applies to the new upload.

Import from a URL

With a key, send application/json with { "url": "https://…" } instead of a file. The image or PDF is fetched server-side (https only) and stored. expires_in, visibility, folder and metadata go next to url.

curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "expires_in": 86400}'

Upload many images at once

POST /v1/images/batch uploads up to 50 base64 images in one request, grouped into a collection (e.g. one CI run). Keyed only. It is partial-failure tolerant — each item reports ok independently, so one bad image doesn't sink the batch; failed items carry their own error code (for example invalid_metadata or a quota code). Re-running with the same (type, name) upserts the same collection, so it's idempotent.

# One request, one collection, up to 50 images.
B64=$(base64 < diff.png | tr -d '\n')
curl -X POST https://api.pixelvault.dev/v1/images/batch \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": { "type": "ci_build", "name": "run-123", "visibility": "private" },
    "images": [ { "data": "'"$B64"'", "filename": "diff.png" } ]
  }'

→ { "data": { "collection_id": "col_…", "items": [
     { "filename": "diff.png", "id": "img_…", "url": "https://img.pixelvault.dev/…", "ok": true }
   ] } }

collection.visibility: "private" returns a signed URL per image; "public" returns a plain CDN URL. Optional: expires_in (image TTL), sign_expires_in (signature lifetime, default 7 days), and freeform metadata on the collection and per image. A batch counts once against the per-minute rate limit.

Read, list and delete

# read one image (metadata, description, URLs)
curl https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

# delete it: removes it from storage and the CDN
curl -X DELETE https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

GET /v1/images/:id returns a single image's metadata by ID. GET /v1/images lists the project's images (paginated; filter by collection, metadata, AI tag, or search descriptions). DELETE /v1/images/:id removes the image from storage and the CDN.

Next steps