Image Upload API Reference

Using OpenClaw? Install the image hosting skill.

Using n8n? Download image hosting workflows for Google Drive and generated image URLs.

Quickstart

Get your first image hosted in 30 seconds. No signup form, no dashboard — just API calls. Prefer to try it in your browser first? Drop an image into the free image-to-URL tool.

1. Register an account

Response:

2. Upload an image

Response:

3. Use the URL

The CDN URL is live immediately. Use it in markdown, HTML, or anywhere you need an image.

![Screenshot](https://img.pixelvault.dev/proj_xyz789/img_abc123.png)

Authentication

All API requests (except registration) require a Bearer token:

Authorization: Bearer pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys use the prefix pv_live_ for production and pv_test_ for test environments. Keys are hashed server-side — we never store the raw key.

API Reference

Base URL: https://api.pixelvault.dev

All responses are JSON. Successful responses wrap the payload in a top-level data object; errors return an error object instead:

Plan quotas (storage, monthly uploads, private images) return 402, not 429: retrying cannot succeed until you delete images, upgrade, or the month resets. See Rate limits & quotas for the error codes.

POST /v1/auth/register

Create a new account. Returns an account, a default project, and an API key. The password is optional — omit it for a passwordless account (ideal for agents); the owner can set one later via the reset flow to enable dashboard login.

POST /v1/images

Upload an image. Accepts multipart/form-data (a file) or, with an API key, application/json (a URL).

Custom metadata: attach a JSON object (up to 50 top-level keys, 4 KB) at upload, replace it later with PATCH /v1/images/{id} and {"metadata": {...}} (null clears it), and find images again with GET /v1/images?metadata={"env":"prod"} or ?meta[env]=prod. All pairs must match. It is returned as metadata on every image. 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. Don't store secrets in it.

AI descriptions: send describe=true with a keyed upload and PixelVault writes alt text, a caption, OCR text and tags in the background. See AI descriptions & tags. describe is ignored when dedupe or an idempotency replay returns an existing image.

Supported formats: JPEG, PNG, GIF, WebP, AVIF, SVG. The response includes width and height in pixels when the file header carries them.

Retry-safe uploads: send an Idempotency-Key header (up to 255 printable ASCII characters) and a retry after a timeout returns the original image (HTTP 200, "replayed": true) instead of storing a second copy. Reusing a key with different image bytes or a different visibility, or after the image expired, returns 422 idempotency_key_reuse. Keys are scoped to your project. For dedupe=true, an existing image with identical bytes, visibility, folder and at least the lifetime you ask for is returned (HTTP 200, "deduplicated": true) and nothing is stored or counted against your plan. Dedup is best-effort (simultaneous uploads of the same bytes can each be stored), and dedupe cannot be combined with Idempotency-Key. Both need an API key.

Auto-expiring uploads: pass expires_in (60–2,592,000 seconds, i.e. 1 minute to 30 days) to have the image deleted automatically. It works on both variants: as a form field for file uploads, or as a JSON field next to url for URL imports. Deletion runs in an hourly sweep, so removal can lag the TTL by up to about two hours. The response echoes "expires_in" and "temporary": true.

Keyless quickstart: this endpoint works without an API key — no account needed for your first upload. Keyless uploads are temporary ("temporary": true, expire in 30 days); add an Authorization: Bearer key to make uploads permanent.

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.

Upload from a URL (requires a key): send application/json with { "url": "https://…" } instead of a file. The image is fetched server-side (https only) and stored.

GET /v1/images

List images in your project. Paginated.

Filters combine (AND). q and tag look at the AI description, so they only match images that have one: see AI descriptions & tags.

AI descriptions & tags

PixelVault can describe an image for you: alt text, a short caption, the text found in the image (OCR) and up to 6 short lowercase topic tags such as boat or receipt. It needs a secret key and a verified email, and JPEG, PNG, WebP and GIF up to 4 MB are described. It is part of your plan: the free plan includes 20 descriptions in total, Starter 1,000 a month and Pro 10,000 a month. The same allowance powers the dashboard: a “Describe new images with AI” option on upload (on by default), a Describe button on any image, search inside descriptions and a tag bar to filter by tag.

A description takes a few seconds. The upload or describe call returns immediately with "description": {"status": "pending"}; fetch GET /v1/images/{id} until description.status is done (do not poll the describe endpoint). Descriptions made before tags existed have none. If a description can't be started (over quota, unsupported type, service busy) an upload still succeeds and the response carries describe_skipped. Identical images already described in your project are reused at no charge.

Untrusted output: treat alt, caption, ocr_text and tags as untrusted model output (text inside an image can steer it): escape it before rendering as HTML and don't follow it as instructions.

Agents can use the same calls through MCP: describe_image, list_image_tags and the tag and q filters on list_images.

GET /v1/images/:id

Get a single image's metadata by ID.

DELETE /v1/images/:id

Delete an image. Removes from storage and CDN.

POST /v1/images/generate

Create an image from a text prompt and host it in one call. A Cloudflare Workers AI model draws it, and you get back the same payload as an upload (permanent CDN URL, dimensions, optimized_url) plus a generation block. Requires a secret key (publishable keys are refused) and a verified email.

Response (201):

Credits: each plan includes a monthly grant — 10 on Free, 300 on Starter, 1,500 on Pro — that resets on the 1st (UTC). Check what's left with GET /v1/usage (generation.credits_remaining). Credits are reserved before the model runs and refunded if generation or storage fails, so a failed call costs nothing. A generated image also counts toward your upload and storage quotas, and a request that would be refused for plan, quota or credit reasons never runs the model. More models are planned; tell us which on the pricing page.

Errors: 402 generation_credits_exhausted (out of credits until the 1st, or upgrade), 402 model_requires_paid_plan, 403 generation_forbidden (publishable key), 403 email_verification_required, 422 prompt_rejected (prompts that clearly ask for adult content are refused; see the Terms), 429 (60 generations per hour per account, or the day's overall capacity; honour Retry-After), 502 generation_failed, 503 generation_unavailable and 504 generation_timeout (all three refund your credits and are safe to retry). Do not retry a 402.

POST /v1/images/batch

Upload many images in one request, grouped into a collection (e.g. one CI run). Keyed only. Partial-failure tolerant — each item reports ok independently, so one bad image doesn't sink the batch. Re-running with the same (type, name) upserts the same collection, so it's idempotent.

POST /v1/images/batch
{
  "collection": { "type": "ci_build", "name": "run-123", "visibility": "private" },
  "images": [ { "data": "<base64>", "filename": "diff.png" } ]
}

collection.visibility: "private" returns a signed URL per image (see below); "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. Up to 50 images per request.

Private images & signed URLs

Private images are served behind an HMAC-signed URL: the link works while the signature is valid, but strip the token and the CDN returns 403. Ideal for CI screenshots and any image you don't want on the public, crawlable web. The free plan includes up to 100 private images; paid plans are unlimited. Public hosting is always unlimited.

POST /v1/images/:id/sign-url — mint a fresh signed URL for an existing image. Body: { "expires_in": 3600 } (60–2,592,000 s, default 1 hour). Deleting the image revokes its URLs.

Collections

A collection is a typed group of images (a CI run, a generation set, an album) with shared metadata and its own lifecycle.

• GET /v1/collections?type=&name= — list your collections.
• GET /v1/collections/:id — a collection and its images.
• GET /v1/images?collection_id=… — filter images by collection.
• POST /v1/collections/:id/close — close a collection (CI collections reap their images on close).

Export all images

Download every image in a project — plus a manifest.json mapping ids, filenames, storage keys, URLs, and metadata — as a single .tar archive. Free on every plan: your data is always portable, no lock-in. A large project is assembled in the background, so it's a start → poll → download flow. Project-scoped: use a secret key, or a dashboard token with ?project_id=.

POST /v1/export
→ 202 { "job_id": "exp_…", "status": "pending", "image_count": 327,
        "status_url": "/v1/export-jobs/exp_…" }

GET /v1/export-jobs/:id
→ { "status": "processing", "processed_count": 120, "image_count": 327 }
   # when status is "complete", the response adds "download_url"

GET /v1/export-jobs/:id/download   # streams application/x-tar once complete

Poll the status URL until status is complete (pending → processing → complete, or failed/expired), then download. Archives expire 24 hours after they're built. The CLI (pixelvault export) and the dashboard both wrap this in one step.

Usage & quota

Check your plan, limits and current usage before a bulk upload. Requires a secret key; scoped to that key's project.

GET /v1/usage
→ { "data": {
     "plan": "free", "period": "2026-10", "resets_at": "2026-11-01T00:00:00.000Z",
     "usage":     { "storage_bytes": 1048576, "uploads": 12 },
     "limits":    { "storage_bytes": 209715200, "uploads_per_month": 500,
                    "bandwidth_bytes_per_month": 1073741824 },
     "remaining": { "storage_bytes": 208667000, "uploads": 488 },
     "generation": { "credits_used": 1, "credits_limit": 10, "credits_remaining": 9 }
   } }

Storage is the cumulative total; uploads count the current UTC month and reset at resets_at. Bandwidth usage isn't reported (the CDN owns those counters), only its limit. Limits per plan are on Rate limits & quotas.

API keys

Manage the keys on your project from the API, so an agent can rotate its own credentials. All three endpoints need a secret key (pv_live_/pv_test_); publishable keys get 403.

# list keys: id, type, environment, label, key_prefix, created_at, last_used_at, current
GET    /v1/keys
# body (optional): { "label": "ci", "environment": "live" }
# → 201, includes the raw "api_key" ONCE
POST   /v1/keys
# revoke a key
DELETE /v1/keys/:id

Hashes and raw keys are never returned by the list. A project can hold at most 25 keys (409 key_limit_reached), and creating or revoking keys is limited to 20 changes per hour per project. Only secret keys can be revoked here (publishable keys are managed in the dashboard). A key can't revoke itself (409 cannot_revoke_current_key), so to rotate: create a new key, switch to it, then revoke the old one with the new key. The 25-key cap is exact, and a revoke only applies while the key making the request still exists, so two keys revoking each other at the same moment cannot leave the project without a key (the loser gets 409 conflict).

Upgrade & billing

An agent can start an upgrade without a dashboard session. Both endpoints need a live secret key (pv_live_; a dashboard token also works) and return a Stripe URL for a person to open. Nothing is charged by the API call itself. Show the URL only to the account owner: the portal can cancel the subscription.

# { "plan": "starter" | "pro" }  → { "url": "https://checkout.stripe.com/..." }
POST /v1/billing/checkout
# → { "url": "https://billing.stripe.com/..." }  (change plan, payment details, cancel)
POST /v1/billing/portal

The plan changes only after Stripe confirms payment, so poll GET /v1/usage for plan rather than assuming success. Checkout needs a verified email (403 email_not_verified) and returns 409 already_subscribed if a subscription exists, in which case use the portal. The portal returns 404 no_subscription before a first purchase. Publishable keys (publishable_key_forbidden) and test keys (test_key_forbidden) get 403. Each endpoint is limited to 10 requests per hour per account (429). For prices and what cancelling does, see Billing & subscriptions.

Sign in with an emailed code

For tools and agents that already have an account but no key: a passwordless, browser-free sign-in. The first call emails a 6-digit code (valid 10 minutes, one per 60 seconds); the second exchanges it for a new secret key. It creates the account if the email is new, exactly like /v1/auth/register, and needs a mailbox you or your user can read.

# { "email": "dev@example.com" }  → { "data": { "sent": true } }
POST /v1/auth/device/start
# { "email": "...", "code": "123456", "label": "my-agent" }
# → api_key, key_id, project_id
POST /v1/auth/device/complete

The key is shown once. Each completion adds a key (default label PixelVault Desktop; list and revoke them under API keys). Pass "replace_existing": true to delete older live keys with the same label, so reconnecting does not pile them up. A code allows 3 attempts, and the auth endpoints share a limit of 5 requests per minute per IP.

CI screenshots (GitHub Action)

For GitHub Actions, the PixelVault screenshots action wraps the batch endpoint: on a failed run it uploads your Playwright / visual-regression screenshots and posts a sticky comment to the pull request. See the walkthrough.

Image transforms

Every CDN URL supports on-the-fly transforms via query params — no extra API call. The edge resizes, crops, and converts the image, then caches the result globally. Available on all plans. See every param on live images on the Images page.

https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=400&fit=cover&fmt=webp

Background removal isolates the subject and makes the background transparent:

# transparent PNG cut-out
.../img_abc123.jpg?segment=foreground
# subject on a white fill
.../img_abc123.jpg?segment=foreground&background=white
# portrait cut-out
.../img_abc123.jpg?w=400&h=400&fit=cover&gravity=face&segment=foreground

Effects (blur, sharpen, rotate, flip, brightness, contrast, saturation) stack and combine with resize/crop:

.../img_abc123.jpg?blur=30                       # blurred
.../img_abc123.jpg?saturation=0                  # grayscale
.../img_abc123.jpg?rotate=90&flip=h              # rotated + mirrored
.../img_abc123.jpg?w=800&blur=30&saturation=0    # grayscale, blurred 800px thumbnail

Watermark tiles one of your own images over the base — upload the watermark once, then reference it by its image id and extension:

.../img_abc123.jpg?tile=img_logo.png             # your logo, tiled at native size
.../img_abc123.jpg?w=1200&tile=img_wm123.png   # resized + watermarked

Background removal, face-crop, effects, and watermark (segment, gravity, zoom, blur, sharpen, rotate, flip, brightness, contrast, saturation, tile) apply to your project images, not the anonymous playground. Invalid params are ignored — you get the original image back, never an error. SVG sources are served as-is (not transformed).

CLI

The pixelvault-cli package gives you one-liner uploads from any terminal. Designed for AI coding agents — URLs go to stdout, messages to stderr.

npm install -g pixelvault-cli

Or use directly with npx:

# Create account, stores API key
npx pixelvault-cli register
# Headless/agent signup, no password
npx pixelvault-cli register --email you@example.com --passwordless
# Prints CDN URL to stdout
npx pixelvault-cli upload photo.jpg
# One URL per line
npx pixelvault-cli list
# Print URL, or download with -o (and -t to transform)
npx pixelvault-cli get img_abc
# Silent on success
npx pixelvault-cli delete img_abc
# Download all your images as a .tar (manifest + every image)
npx pixelvault-cli export

upload options — bulk-upload with a shell glob, organize into a folder, upload privately (signed URL), or emit the full JSON:

# Bulk upload (shell glob), grouped in a folder
npx pixelvault-cli upload *.png --folder icons
# Full JSON response instead of the bare URL
npx pixelvault-cli upload shot.png --json
# Private signed URL (needs a secret key)
npx pixelvault-cli upload secret.png --private
# …with a 24h link lifetime (default 7d)
npx pixelvault-cli upload secret.png --private --expires 24h

optimize compresses images on your machine — no account, no API key, nothing is uploaded. It resizes, converts and strips metadata, never writes a file bigger than the original, and is safe to re-run in a hook or CI:

# Writes hero.optimized.png next to the original
npx pixelvault-cli optimize hero.png
# A folder to WebP, capped at 1600px wide, into ./optimized
npx pixelvault-cli optimize ./shots -r --format webp --max-width 1600 --out-dir ./optimized
# Preview the saving without writing anything
npx pixelvault-cli optimize ./assets -r --dry-run
# Optimize, upload, and print the CDN URL (needs an API key)
npx pixelvault-cli optimize hero.png --host

Supports JPG, PNG, WebP and AVIF (needs Node 20.9+). For an image that is already hosted, use the CDN params instead (?fmt=webp&q=75&w=1600) or the optimized_url returned on upload.

For CI/CD and headless agent usage, set PIXELVAULT_API_KEY:

export PIXELVAULT_API_KEY=pv_live_xxx
npx pixelvault-cli upload screenshot.png

Source: github.com/pixelvault-dev/cli

SDKs

Official client libraries for JavaScript/TypeScript and Python. Both read PIXELVAULT_API_KEY, retry rate limits and idempotent requests, and raise a typed error with the API's code.

npm install @pixelvault-dev/sdk      # Node 18+, Workers, Deno, Bun, browsers
pip install pixelvault               # Python 3.9+, sync and asyncio

import { PixelVault } from "@pixelvault-dev/sdk";

const pv = new PixelVault();           // reads PIXELVAULT_API_KEY
const image = await pv.images.upload({
  file: bytes, filename: "shot.png", contentType: "image/png",
});
console.log(image.url);
await pv.images.upload({ url: "https://example.com/a.png", expiresIn: 3600 });

from pixelvault import PixelVault

pv = PixelVault()                      # reads PIXELVAULT_API_KEY
image = pv.images.upload("shot.png")
print(image["url"])
pv.images.upload(url="https://example.com/a.png", expires_in=3600)

Both cover uploads (file or URL import, expires_in, private), batch uploads, listing, signed URLs, usage and API keys. Without an API key, an upload is anonymous and expires after 30 days. Sources: sdk-js and sdk-python.

Claude Code skill

PixelVault ships a Claude Code skill so your agent can upload images without leaving the conversation.

claude plugin add pixelvault-dev/skill

Once installed, the skills include:

The upload skill can also be triggered automatically — when Claude sees "upload this screenshot" or needs to host an image, it invokes the skill without you typing the command.

The skill wraps the pixelvault-cli, so make sure it's installed first (or run /pixelvault-setup).

Source: github.com/pixelvault-dev/skill

Paste & host (browser widget)

Let your own users paste, drop, or select an image in a textarea and get a hosted CDN URL inserted automatically — the same flow as GitHub's markdown editor, on your site. It runs entirely in the browser with a publishable key, so there's no server code to write.

1. Create a publishable key

In your dashboard, open a project's Publishable keys section and add one with an allowlist of the origins it may be used from (for example https://app.example.com). Publishable keys (pv_pub_…) are safe to ship in browser code: they are upload-only and rejected from any origin that isn't on the allowlist.

2a. Drop-in script tag

Zero build step. Add one tag; every field matching data-pv-target becomes paste-and-host:

<textarea data-pixelvault></textarea>
<button data-pv-pick="[data-pixelvault]">Upload image</button>
<script src="https://pixelvault.dev/paste.js"
        data-pv-key="pv_pub_xxxxxxxx"
        data-pv-target="[data-pixelvault]"></script>

Attributes on the tag: data-pv-key (required), data-pv-target (CSS selector; defaults to [data-pixelvault]), and optional data-pv-endpoint / data-pv-folder. Add a data-pv-pick attribute to any button (its value is the target field's selector) to open the file picker on click. The script also exposes a global window.PixelVaultPaste with attach, openFilePicker, and init for wiring elements added later.

2b. npm package

For bundled apps, install the framework-agnostic core:

npm install @pixelvault-dev/paste

import { attachPaste, openFilePicker } from "@pixelvault-dev/paste";

const field = document.querySelector("textarea");
const options = { publishableKey: "pv_pub_xxxxxxxx" };

attachPaste(field, options);                       // paste + drop
uploadButton.addEventListener("click", () => openFilePicker(field, options));

Or a framework binding:

// npm install @pixelvault-dev/paste-react
import { useRef } from "react";
import { usePaste } from "@pixelvault-dev/paste-react";

function Editor() {
  const ref = useRef(null);
  const { openFilePicker } = usePaste(ref, { publishableKey: "pv_pub_xxxxxxxx" });
  return (
    <>
      <textarea ref={ref} />
      <button onClick={openFilePicker}>Upload image</button>
    </>
  );
}

<!-- npm install @pixelvault-dev/paste-vue -->
<script setup>
  import { ref } from "vue";
  import { usePaste } from "@pixelvault-dev/paste-vue";

  const field = ref(null);
  const { openFilePicker } = usePaste(field, { publishableKey: "pv_pub_xxxxxxxx" });
</script>

<template>
  <textarea ref="field" />
  <button @click="openFilePicker">Upload image</button>
</template>

3. What the user sees

Pasting, dropping, or picking an image inserts an ![Uploading…]() placeholder at the caret, uploads the file, then swaps in ![name](https://img.pixelvault.dev/…). Override the inserted text (HTML, BBCode, a bare URL) with the render option, and hook onUploadStart, onUploadComplete, and onError for progress and error handling.

Images in email (Resend / react-email)

Gmail doesn't render base64 data: images and many Outlook clients don't either, so every image in an email has to point at a public URL. Resend sends the email but doesn't host images, so host them on PixelVault first and reference the returned URL. Because it's a permanent, immutable CDN URL on zero-egress storage, it renders for the life of the inbox and costs the same no matter how many times the email is opened.

A tiny helper uploads a local asset and hands back the CDN URL (server-side — it uses your secret API key):

// email-images.ts — host a local asset once, get a permanent CDN URL.
import { readFile } from "node:fs/promises";
import { basename } from "node:path";

const API = "https://api.pixelvault.dev/v1/images";

export async function hostForEmail(path: string): Promise<string> {
  const form = new FormData();
  form.append("file", new Blob([await readFile(path)]), basename(path));

  const res = await fetch(API, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}` },
    body: form,
  });
  if (!res.ok) throw new Error(`PixelVault upload failed: ${res.status}`);

  const { data } = await res.json(); // the URL is nested under `data`
  return data.url; // https://img.pixelvault.dev/proj_abc/img_xyz.png
}

The URL is permanent, so host each asset once — a prep script or CI step — and save the URL (an env var works). Don't call this per send, or you'll mint a new URL and burn an upload every time:

// prep.ts — run ONCE (a script or CI step). The URL is permanent,
// so host the asset a single time and save the URL, e.g. to an env var.
import { hostForEmail } from "./email-images";

const logoUrl = await hostForEmail("./assets/logo.png");
console.log(logoUrl); // → store as EMAIL_LOGO_URL; never re-host per send

Pass that saved URL into your react-email template as a prop and render it with <Img>. Serve a 2× image and constrain it with width for crisp retina — the transform params resize on the fly:

// receipt.tsx — the hosted URL comes in as a prop (no per-render upload).
import { Img } from "@react-email/components";

export function Receipt({ logoUrl }: { logoUrl: string }) {
  // Serve at 2× (w=240), display at 120 — crisp on retina.
  return <Img src={`${logoUrl}?w=240&fmt=auto`} width="120" alt="Acme" />;
}

Then render the template to HTML and send it (this file is .tsx — it contains JSX):

// send.tsx — render with the pre-hosted URL and hand the HTML to Resend.
import { Resend } from "resend";
import { render } from "@react-email/render";
import { Receipt } from "./receipt";

const resend = new Resend(process.env.RESEND_API_KEY);
const logoUrl = process.env.EMAIL_LOGO_URL!; // hosted once, saved earlier

await resend.emails.send({
  from: "receipts@yourdomain.com",
  to: "customer@example.com",
  subject: "Your receipt",
  html: await render(<Receipt logoUrl={logoUrl} />),
});

Not on react-email? The same idea works with any templating: call hostForEmail() once, save the URL, then interpolate it into your <img src>. See the full walkthrough.

MCP server

PixelVault runs two Model Context Protocol servers, so any MCP-capable agent (Claude, Cursor, and others) can host images directly: a remote one for URLs and base64, and a local one for files on disk. Start with the hosted server: there is nothing to install, it works with remote clients, and it gets new tools first. Add the local one only if you need to upload files by path (compare the two). The remote server is hosted on Cloudflare's edge at:

https://mcp.pixelvault.dev/mcp   (transport: streamable-http)

These tools are exposed:

Authenticate by sending your API key as a Bearer token. Add it to Claude Code with:

claude mcp add --transport http pixelvault https://mcp.pixelvault.dev/mcp \
  --header "Authorization: Bearer pv_live_xxxxxxxx"

Or configure any client that supports the streamableHttp transport:

{
  "mcpServers": {
    "pixelvault": {
      "type": "streamable-http",
      "url": "https://mcp.pixelvault.dev/mcp",
      "headers": { "Authorization": "Bearer pv_live_xxxxxxxx" }
    }
  }
}

OAuth (for ChatGPT apps and other OAuth clients): connect to https://mcp.pixelvault.dev/mcp/oauth instead — no key to paste. You authorize through a short email-code consent screen and PixelVault mints a per-user key behind the scenes. The /mcp endpoint above (API key) stays available for existing clients.

Hosted or local?

Rule of thumb: use the hosted server by default, and add the local one next to it if your agent uploads files from disk. They don't conflict.

Local MCP server (upload by file path)

The hosted server runs on Cloudflare's edge, so it cannot read your filesystem — a local file has to be inlined as base64, which pushes the whole image through the model's context. For files on disk, run the local server alongside it. It speaks stdio and carries seven of the tools above — upload_image, transform_image, list_images, get_image, update_image_metadata, delete_image, sign_url (no upload_batch or rescue_imgur) — with upload_image also accepting a path:

claude mcp add pixelvault-local \
  --env PIXELVAULT_API_KEY=pv_live_xxxxxxxx \
  -- npx -y @pixelvault-dev/local-mcp

Or configure it directly:

{
  "mcpServers": {
    "pixelvault-local": {
      "command": "npx",
      "args": ["-y", "@pixelvault-dev/local-mcp"],
      "env": { "PIXELVAULT_API_KEY": "pv_live_xxxxxxxx" }
    }
  }
}

upload_image takes path (read off disk), source_url, or base64 data. It reads the key from PIXELVAULT_API_KEY or ~/.pixelvault/config.json, the same as the CLI. Source is on GitHub (MIT); published as @pixelvault-dev/local-mcp.

ChatGPT (Custom GPT Action)

Add PixelVault to a ChatGPT Custom GPT as an Action, so the GPT can host and manage images. Import this trimmed OpenAPI spec — built specifically for GPT Actions (single server, JSON only):

https://pixelvault.dev/openapi-actions.json

In the GPT editor, open Configure → Actions → Import from URL and paste the URL above. Then set Authentication → API Key, choose Bearer, and paste a pv_live_ key from your dashboard.

Six actions are available:

GPT Actions can't send file uploads, so upload_image takes a public image URL rather than a file. Once hosted, apply transforms by appending query params to the returned URL. Need base64 uploads, describing images or the full tool set? Use the MCP server instead.

Agent discovery

PixelVault provides standard discovery endpoints for any AI agent:

• /.well-known/api-catalog — API catalog for agent discovery
• /llms.txt — LLM-readable service description (lists the MCP server)
• /openapi.json — OpenAPI 3.1 specification
• /openapi-actions.json — trimmed spec for ChatGPT Custom GPT Actions
• MCP server — https://mcp.pixelvault.dev/mcp (API key) or /mcp/oauth (OAuth)
• /.well-known/agent-skills/index.json — agent skills catalog (/.well-known/skills/index.json serves the same skills in Hermes Agent format, for hermes skills install well-known:…)