<!-- Markdown twin of https://pixelvault.dev/docs/guides/upload-images/ -->

# Upload images & PDFs

**Goal:** turn a local file or a remote URL into a permanent CDN URL you can embed anywhere. Prefer a browser? Use the free [image-to-URL](/tools/image-to-url/) or [PDF-to-URL](/tools/pdf-to-url/) tools.

## Upload a file

Send `multipart/form-data` with a `file` field to [`POST /v1/images`](/docs/api/images/#upload_image):

Upload

curlNode.jsPythonCLI

```
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -F "file=@screenshot.png" \
  -F "folder=docs"
```

The response (`201`) carries the image `id`, its CDN `url`, `mime_type`, `size`, and `width`/`height` when the file header has them. The URL is live immediately.

-   **Formats**: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF. Images return `kind: "image"`. Max size per image is 5/10/15 MB on Free/Starter/Pro ([limits](/docs/limits/)).
-   **PDFs** return `kind: "document"`, always download with `Content-Disposition: attachment`, are marked `noindex`, and reject image transform parameters.
-   **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. Any other size or format is a [transform URL](/docs/transforms/) away.
-   **Optional fields**: `folder` and `metadata` ([organize](/docs/guides/organize-media/)), `visibility=private` ([signed URLs](/docs/private-media/)), `expires_in` ([auto-delete](/docs/lifecycle/)), `describe=true` ([AI alt text and tags](/docs/guides/ai-descriptions/)), `dedupe=true` (reuse an identical existing image).
-   **Retries**: send an `Idempotency-Key` header so a retry after a timeout returns the original image instead of storing a second copy. See [Idempotency](/docs/idempotency/).

## Without an API key

Multipart uploads work _without_ an API key — no account needed for your first upload. Keyless uploads are temporary (`"temporary": true`, expire in 30 days) and ignore metadata and idempotency keys. For a managed image or PDF without that fixed expiration, re-upload with an `Authorization: Bearer` key and use the new URL. The original anonymous URL still expires; free-plan retention applies to the new upload.

## Import from a URL

With a key, send `application/json` with `{ "url": "https://…" }` instead of a file. The image or PDF is fetched server-side (https only) and stored. `expires_in`, `visibility`, `folder` and `metadata` go next to `url`.

```
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "expires_in": 86400}'
```

## Upload many images at once

[`POST /v1/images/batch`](/docs/api/images/#batch_upload) uploads up to 50 base64 images in one request, grouped into a [collection](/docs/guides/organize-media/#collections) (e.g. one CI run). Keyed only. It is partial-failure tolerant — each item reports `ok` independently, so one bad image doesn't sink the batch; failed items carry their own error code (for example `invalid_metadata` or a quota code). Re-running with the same `(type, name)` upserts the same collection, so it's idempotent.

```
# One request, one collection, up to 50 images.
B64=$(base64 < diff.png | tr -d '\n')
curl -X POST https://api.pixelvault.dev/v1/images/batch \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": { "type": "ci_build", "name": "run-123", "visibility": "private" },
    "images": [ { "data": "'"$B64"'", "filename": "diff.png" } ]
  }'

→ { "data": { "collection_id": "col_…", "items": [
     { "filename": "diff.png", "id": "img_…", "url": "https://img.pixelvault.dev/…", "ok": true }
   ] } }
```

`collection.visibility: "private"` returns a **signed URL** per image; `"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. A batch counts once against the per-minute rate limit.

## Read, list and delete

```
# read one image (metadata, description, URLs)
curl https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

# delete it: removes it from storage and the CDN
curl -X DELETE https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

[`GET /v1/images/:id`](/docs/api/images/#get_image) returns a single image's metadata by ID. [`GET /v1/images`](/docs/api/images/#list_images) lists the project's images ([paginated](/docs/pagination/); filter by collection, metadata, AI tag, or search descriptions). [`DELETE /v1/images/:id`](/docs/api/images/#delete_image) removes the image from storage and the CDN.

## Next steps

-   [Resize and convert](/docs/transforms/) the uploaded image with URL parameters.
-   [Organize media](/docs/guides/organize-media/) with folders, metadata and collections.
-   [Host CI screenshots](/docs/guides/ci-screenshots/) with the batch endpoint.
