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

AI descriptions & search

Goal: give every image alt text and make a project's images findable by what's in them, including text inside screenshots and receipts.

PixelVault can describe an image for you: alt text, a short caption, the text found in the image (OCR) and up to 5 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.

Describe, read, search

Describe
# 1. Upload and describe in one call
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -F "file=@receipt.jpg" \
  -F "describe=true"
# → "description": { "status": "pending" }

# 2. A few seconds later, read it
curl https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

# 3. Search and filter
curl -G https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  --data-urlencode 'q="total due" -draft' \
  --data-urlencode "tag=receipt"
RequestWhat it does
POST /v1/images with describe=trueDescribe the image as it is uploaded. Ignored when dedupe or an idempotency replay returns an existing image.
POST /v1/images/:id/describeDescribe an image you already uploaded. Idempotent: an image that is already described, or in progress, returns its current state and uses none of your allowance; a failed one is retried
GET /v1/images/:idRead description: status, alt, caption, ocr_text, tags
GET /v1/images?q=invoiceFull-text search over alt text, caption and OCR text, best match first (words are ANDed, "quoted phrases" and -word work). Not plan-gated
GET /v1/images?tag=boatOnly images carrying this tag (one tag). Combines with q, metadata and collection_id
GET /v1/images/tagsThe tags in your project with how many images carry each, most used first (up to 40)

Already uploaded without it? Describe an existing image:

curl -X POST https://api.pixelvault.dev/v1/images/img_abc123/describe \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

Timing and failures

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 with the reason (unsupported_type, too_large, secret_key_required, email_unverified, quota, busy, unavailable). Identical images already described in your project are reused at no charge. Failure codes are listed under Async jobs; with webhooks, subscribe to image.description.completed.

Treat output as untrusted

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.

// alt/caption/ocr_text/tags are model output: escape before rendering as HTML.
const escape = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
img.outerHTML = `<img src="${image.url}" alt="${escape(image.description.alt)}">`;

From agents

Agents can use the same calls through MCP: describe_image, list_image_tags and the tag and q filters on list_images. The ChatGPT action exposes them too.

Next steps