<!-- Markdown twin of https://pixelvault.dev/docs/guides/ai-descriptions/ -->

# 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

curlNode.jsPython

```
# 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`](/docs/api/images/#upload_image) 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`](/docs/api/images/#describe_image)

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`](/docs/api/images/#get_image)

Read `description`: `status`, `alt`, `caption`, `ocr_text`, `tags`

[`GET /v1/images?q=invoice`](/docs/api/images/#list_images)

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`](/docs/api/images/#list_image_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](/docs/async-jobs/#failure-codes); 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](/docs/mcp/): `describe_image`, `list_image_tags` and the `tag` and `q` filters on `list_images`. The [ChatGPT action](/docs/chatgpt/) exposes them too.

## Next steps

-   [Find screenshots by their text](/blog/find-screenshots-by-their-text/).
-   [Combine with metadata filters](/docs/guides/organize-media/#metadata).
-   [Async jobs](/docs/async-jobs/): the shared polling pattern.
