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
# 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" | Request | What it does |
|---|---|
POST /v1/images with describe=true | Describe the image as it is uploaded. Ignored when dedupe or an idempotency replay returns an existing image. |
POST /v1/images/:id/describe | Describe 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/:id | Read description: status, alt, caption, ocr_text, tags |
GET /v1/images?q=invoice | Full-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=boat | Only images carrying this tag (one tag). Combines with q, metadata and collection_id |
GET /v1/images/tags | The 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
- Find screenshots by their text.
- Combine with metadata filters.
- Async jobs: the shared polling pattern.