<!-- Markdown twin of https://pixelvault.dev/image-upload-api/ -->

Image upload API

# An image upload API  
that returns a CDN URL.

POST a file, a remote URL or a batch of up to 50 images. Get a CDN URL back for each one. Idempotency keys for safe retries, server-side validation, free to start.

[Get your API key](/signup/) [Read the docs](/docs/)

## Three ways to upload

An API key unlocks all three. Multipart file uploads also work without one and return a temporary 30-day URL. A single upload returns `{ data: { id, url, … } }`; a batch returns `{ data: { collection_id, items } }` with one result per image.

File URL Batch Node Python

\# Multipart file upload  
curl \-X POST https://api.pixelvault.dev/v1/images \\  
  \-H "Authorization: Bearer $PIXELVAULT\_API\_KEY" \\  
  \-H "Idempotency-Key: build-4821-hero" \\  
  \-F "file=@photo.jpg"  
  
\# { "data": { "id": "img\_xyz", "url": "https://img.pixelvault.dev/proj\_abc/img\_xyz.jpg", ... } }

## Limits and behavior, up front

The details that usually surface in production. All of them are enforced by the API, not just documented.

### 5 MB free, up to 15 MB paid

5 MB on the free plan and for keyless uploads, 10 MB on Starter, 15 MB on Pro. A multipart upload over your cap returns `413`; a URL import fails with `400`; a batch item reports `file_too_large`.

### Images plus PDF

JPEG, PNG, GIF, WebP, AVIF, SVG and PDF. Types are detected from magic bytes, so a renamed file can't slip through. SVGs containing scripts are rejected; PDFs always download and cannot use image transforms.

### Retry-safe

With an API key, send an `Idempotency-Key` (1–255 printable ASCII characters, no spaces) and a retried single upload returns the same image instead of a duplicate. Or use `dedupe=true`; the two can't be combined.

### URL import

Hand over a public https URL and PixelVault fetches it. Requires an API key. Private and internal addresses are blocked, redirects are capped and the fetch times out.

### Batch with partial failure

With an API key, upload up to 50 images per request (body up to 40 MB), grouped into a collection. Each item succeeds or fails independently. Re-running a collection reuses it but uploads the images again, so it isn't retry-safe.

### Expiry and privacy options

Set `expires_in` (up to 30 days) for temporary images, or `visibility: private` and serve them through signed URLs.

## Errors your code can branch on

Failures are JSON, never an HTML page: `{ error: { code, message } }`. `401` means a missing or bad key when using an authenticated feature; keyless multipart uploads do not require one. A multipart file over your size cap returns `413`, and other failures return `400` with a specific code such as `invalid_file`, `missing_url` or `validation_error`. A new account that hasn't verified its email gets `403` with `email_verification_required` after 5 uploads. In a batch, failures come back per item with `ok: false`. The full contract is the [OpenAPI 3.1 spec](https://api.pixelvault.dev/openapi.json).

Once uploaded, every public raster image has a CDN URL you can resize and convert with query params: see the [image CDN API](/image-cdn-api/). PDFs are served as download-only attachments; try the free [PDF-to-URL tool](/tools/pdf-to-url/). Looking for the overview? Start with the [image hosting API](/image-hosting-api/). No code yet? Try the free [image-to-URL tool](/tools/image-to-url/). Calling from an agent? See [image hosting for AI agents](/for-ai-agents/).

## Image upload API FAQ

Can I upload without an API key?

Yes. A multipart file upload to /v1/images works without a key and returns a temporary URL that expires after 30 days. Add an API key for managed uploads without that fixed expiration, URL imports, batches, private images, idempotency keys and deduplication. Free-plan retention still applies.

What is the maximum upload size?

5 MB per image or PDF on the free plan and for keyless uploads, 10 MB on Starter and 15 MB on Pro. A multipart upload over your plan's cap is rejected with HTTP 413. A URL import over the cap fails with a 400, and in a batch that item comes back with ok false and a file\_too\_large error. If your source is bigger, reduce it first.

Which file formats can I upload?

JPEG, PNG, GIF, WebP, AVIF, SVG and PDF. Types are detected from the file's bytes, not its filename or Content-Type. SVGs are checked for executable content and served sandboxed. PDFs are opaque download-only documents: they are not sanitized or rendered on PixelVault's domain.

Can I upload from a URL instead of a file?

Yes. POST a JSON body with a url field to the same /v1/images endpoint and PixelVault fetches it for you. The URL must be https and public; private and internal addresses are blocked. URL import needs an API key.

Can I upload base64?

Yes, in the batch endpoint: each item in /v1/images/batch can carry base64 data or a source\_url. The single-image endpoint takes a multipart file or a JSON url.

How do I retry safely after a timeout?

Send an Idempotency-Key header (1–255 printable ASCII characters, no spaces) on a single-image upload. A retry with the same key won't create a duplicate. Alternatively pass dedupe=true to avoid storing identical bytes twice; the two can't be combined. Re-running a batch reuses the collection but uploads the images again.

Do I need to verify my email before uploading?

An unverified account can upload up to 5 images. After that, upload requests return 403 with the error code email\_verification\_required until you verify your email address. Verifying takes a minute, so do it before you wire the API into a pipeline.

Is the upload API free?

The free tier includes 200 MB storage, 500 uploads per month and 1 GB bandwidth, with no credit card. Paid plans raise the caps; see the pricing page.

## Upload your first image in minutes

Free tier: 200 MB storage, 500 uploads/month, no credit card. See [pricing](/pricing/) for paid plans.

[Get your API key](/signup/)
