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:
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 withContent-Disposition: attachment, are markednoindex, 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 (urlplus?fmt=auto&q=85). It is usually much smaller. The original aturlis never changed, so use whichever suits the embed. Any other size or format is a transform URL away. - Optional fields:
folderandmetadata(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-Keyheader 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
- Resize and convert the uploaded image with URL parameters.
- Organize media with folders, metadata and collections.
- Host CI screenshots with the batch endpoint.