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.
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.
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.
Once uploaded, every public raster image has a CDN URL you can resize and convert with query params: see the image CDN API. PDFs are served as download-only attachments; try the free PDF-to-URL tool. Looking for the overview? Start with the image hosting API. No code yet? Try the free image-to-URL tool. Calling from an agent? See image hosting 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 for paid plans.
Get your API key