io.github.pixelvault-dev/pixelvault

Close a collection (e.g. when a PR merges). Maps to POST /v1/collections/:id/close. Call get_collection first and check its `type`: for `ci_build` collections closing makes every image in it eligible for deletion, which a background sweep (hourly, in batches) then carries out permanently, and it cannot be undone; for other types (generation sets, batches) it only marks the collection closed and keeps its images, though an empty closed collection may later be removed. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

Prepare a public image upload from a local shell file when no host attachment download URL exists. Compute the file size and SHA-256 in the shell, then call this tool with filename, size and sha256. Returns a 10-minute URL and curl command to PUT the raw file bytes without an API key or base64. The shell must have network access to this MCP host. The PUT response contains the CDN URL and Markdown. Do not publish the temporary upload URL or retry uploads automatically.

Permanently delete one PixelVault image by id. Maps to DELETE /v1/images/:id. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

Generate an image from a text prompt with a Cloudflare Workers AI model and host it on PixelVault in one call; returns the permanent CDN URL. Maps to POST /v1/images/generate. Spends credits from the monthly grant (free 10, Starter 300, Pro 1500; resets on the 1st, UTC): flux-1-schnell (default), sdxl-lightning and sdxl-base cost 1 credit, lucid-origin and phoenix-1.0 (Leonardo) cost 20; the free plan can use flux-1-schnell only. Credits are refunded if generation fails. Call get_usage first to see the credits left. Prompts that clearly ask for adult content are refused, and the account needs a verified email. The result includes a `generation` block with the credits charged and remaining, and may include `optimized_url` (WebP/AVIF; prefer it when embedding in a page or email). Requires a PixelVault secret API key sent as a Bearer token in the Authorization header. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), effects like ?blur=30&saturation=0&rotate=90, and ?tile=<image_id.ext> (tile another of your images as a watermark). Or call the transform_image tool to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Get one collection and its images by id. Maps to GET /v1/collections/:id. Each image has a `visibility`: for `private` images the returned URL is the plain CDN URL, which returns 403 without a signature, so call sign_url with the image id for a viewable link (a signed URL cannot be combined with transform params). Public images' URLs work as-is and support transforms via transform_image. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

Get metadata (CDN URL, size, MIME type, dimensions) for one PixelVault image by id. Maps to GET /v1/images/:id. Requires a PixelVault API key sent as a Bearer token in the Authorization header. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), effects like ?blur=30&saturation=0&rotate=90, and ?tile=<image_id.ext> (tile another of your images as a watermark). Or call the transform_image tool to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Show your plan, this month's usage (storage, uploads) and what is left of the quota, so you can check before a bulk upload. Maps to GET /v1/usage. Read-only. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

List your project's collections (CI runs, generation sets, albums — what upload_batch creates), newest first. Maps to GET /v1/collections. Optional `type` and `name` filters (name is the CI run id, generation id, etc.) and pagination. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

List images in your PixelVault project, most recent first, optionally filtered by custom metadata or searched by AI description (q: alt text, caption, OCR text, best match first). Maps to GET /v1/images with pagination. Requires a PixelVault API key sent as a Bearer token in the Authorization header. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), effects like ?blur=30&saturation=0&rotate=90, and ?tile=<image_id.ext> (tile another of your images as a watermark). Or call the transform_image tool to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Open the Stripe billing portal to change plan, update payment details or cancel. Maps to POST /v1/billing/portal. Returns a URL for the account owner to open; nothing changes until they act there. The URL can cancel the subscription and change payment details, so show it only to the account owner. Requires a PixelVault live secret API key (pv_live_) sent as a Bearer token in the Authorization header.

Scan a web page for hotlinked Imgur images and return a PixelVault rescue URL for each — a proxy that lazily rehosts the image on first request, keeping it working through the UK Imgur block. The anonymous rescue tier is a durable ~30-day edge cache (see `cache_ttl_days` in the result), not permanent storage. Maps to POST /v1/imgur-scan (server-side page fetch; no API key required). Provide `page_url` (a public https:// page). Drop each returned rescue_url into your HTML to rehost on first request.

Mint a time-limited signed URL for a private image. Maps to POST /v1/images/:id/sign-url. Provide `id` and optional `expires_in` (seconds, default 3600). The signature binds the image, so the URL can't be replayed against another image; strip it and the CDN returns 403. Deleting the image revokes its URLs. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

Build an on-the-fly transform URL for a PixelVault image (resize, crop, format/quality, AI background removal, blur/sharpen/rotate/flip, brightness/contrast/saturation, and same-project watermark tiling). Provide exactly one of `url` (a PixelVault CDN URL) or `id` (an image id, resolved via the API — requires an API key), plus one or more transform params. Returns the ready-to-use CDN URL; the transform is produced and cached on first request. See https://pixelvault.dev/docs#transforms.

Replace one image's custom metadata (a JSON object you can later filter list_images by). The object replaces the stored one, so send every key to keep; null clears it. Maps to PATCH /v1/images/:id. Requires a PixelVault API key sent as a Bearer token in the Authorization header.

Start a paid-plan checkout (`starter` or `pro`). Maps to POST /v1/billing/checkout. Returns a Stripe Checkout URL — it does NOT charge anything: the account owner must open the URL and pay, so show it only to them. The plan changes only after Stripe confirms, so call get_usage afterwards instead of assuming success. Needs a verified email; errors with already_subscribed if a subscription exists (use manage_billing). Requires a PixelVault live secret API key (pv_live_) sent as a Bearer token in the Authorization header.

Upload many images (1–50) in one call, grouped into a collection — e.g. a CI run or a set of generated variants. Maps to POST /v1/images/batch. Each item is `data` (base64) or `source_url` (server-fetched, SSRF-guarded), with optional `filename`/`metadata`. Set `visibility: "private"` to get a signed URL per image (free plan: up to 100 private images) instead of a public CDN URL. Optional `type`/`name` (idempotent by (type, name)), `expires_in` (image TTL), `sign_expires_in` (signature lifetime), and collection `metadata`. Partial-failure tolerant: each returned item has its own `ok`. Requires a PixelVault API key sent as a Bearer token in the Authorization header. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), effects like ?blur=30&saturation=0&rotate=90, and ?tile=<image_id.ext> (tile another of your images as a watermark). Or call the transform_image tool to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Upload an image publicly to PixelVault and get an instant CDN URL. Maps to POST /v1/images. Provide exactly one of `file` (a host-provided attachment), `source_url` (a public http(s) URL the server fetches), or `data` (base64-encoded bytes). Prefer file for attachments; optional `folder`, `filename`, and `expires_in` (seconds, for an auto-expiring image). Pass `idempotency_key` to make retries safe (a repeat returns the original image), or `dedupe: true` to reuse an identical existing image instead of storing another copy. Max 5 MB; JPG/PNG/GIF/WebP/AVIF/SVG. Requires a PixelVault API key sent as a Bearer token in the Authorization header. The result may include `optimized_url`: the same image as WebP/AVIF, usually far smaller; prefer it over `url` when embedding in a page, README or email. For local shell files without a host download URL, use create_upload_url. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), effects like ?blur=30&saturation=0&rotate=90, and ?tile=<image_id.ext> (tile another of your images as a watermark). Or call the transform_image tool to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.