An image upload API that returns ready-to-use links.
Send one authenticated multipart request. Receive validated image details, a share URL, a direct URL, embed formats, expiration data, and current quota information as JSON.
Upload a screenshot with curl
Generate an API key from the account dashboard, place it in an environment variable, then send the file and retention rule. The key belongs in the Authorization header, never in the URL.
Authentication referenceexport IMAGEUPLOAD_API_KEY="iu_live_REPLACE_ME"
curl -X POST "https://imageupload.io/api/upload" \
-H "Authorization: Bearer $IMAGEUPLOAD_API_KEY" \
-F "[email protected]" \
-F "expiration=1w"The response is built for the next step
Use the direct URL in software that expects image bytes. Use the share URL when a person should open a web page. The embed object avoids duplicating formatting logic across clients.
{
"ok": true,
"slug": "Ab3xYz90",
"mime": "image/png",
"width": 1440,
"height": 900,
"expiration": "1w",
"password_protected": false,
"share_url": "https://imageupload.io/i/Ab3xYz90",
"direct_url": "https://imageupload.io/f/Ab3xYz90.png",
"embed": {
"html": "<img src=\"...\" alt=\"screenshot.png\" />",
"bbcode": "[img]...[/img]",
"markdown": ""
},
"quota": {
"used": 1,
"limit": 10,
"remaining": 9,
"plan": "free",
"unlimited": false
}
}Fields that control the upload
Only file is required. Feature and plan checks are enforced by the server, so clients should handle structured error responses.
| Field | Purpose | Notes |
|---|---|---|
| file | Image bytes | One PNG, JPEG, WebP, GIF, or AVIF per request |
| expiration | Retention mode | 1d, 1w, 1mo, 3mo, burn, views, forever, or custom |
| view_limit | Unique-view deletion | Integer from 1 to 999 when expiration is views |
| password | Viewer access | Optional, up to 256 characters |
| folder | Account organization | Existing folder slug owned by the API account |
| custom_slug | Custom link name | Pro or Business, validated and prefixed per account |
| custom_expires_at | Exact expiry time | Future date value for Pro or Business custom expiration |
Plan availability is documented on the pricing page. The complete request contract and language examples are in the docs.
Design clients around explicit limits
Monthly API and MCP quotas are shared. Browser uploads made through an authenticated web session do not consume the Bearer API quota.
Free
10 API or MCP uploads per month, 500 MB storage, 25 MB per file.
Starter
50 API or MCP uploads per month, 5 GB storage, 25 MB per file.
Pro
No monthly count cap, 50 GB storage, 50 MB per file.
Business
No monthly count cap, 500 GB storage, 100 MB per file.
Per-key ceiling: Bearer-authenticated uploads are limited to 60 per minute. Honor Retry-After on a 429 response.
Quota visibility: Successful API responses include quota data and the service also returns used, limit, and remaining quota headers.
Storage enforcement: The processed file size counts against account storage. Delete unused images or upgrade before the limit is reached.
Handle failures by status, not by string matching
Keep the returned error message for logs, but let the HTTP status drive retry, authentication, and user feedback behavior.
400Malformed multipart data, missing file, invalid image, expiration, or custom option.
401Missing, malformed, or unknown API key. Do not retry until credentials change.
403The selected option is not available to the account or moderation rejected the upload.
413File-size or storage quota exceeded. Compress, delete stored images, or change plan.
415Unsupported declared image type. Use one of the documented formats.
429Monthly quota or short-window rate limit reached. Respect the quota response and Retry-After header.
503Image-processing capacity is temporarily full. Retry later with exponential backoff and jitter.
Use the API in application code
REST is the direct fit when your service already controls HTTP requests, multipart files, retries, and secret storage. It gives you the complete upload response in one call.
Browse nine language examplesUse MCP in compatible AI tools
The MCP server uses the same key and limits, then exposes structured tools for upload, listing, image inspection, deletion, folder listing, folder creation, and quota checks.
Follow the MCP setup guideImage upload API questions
How do I authenticate with the image upload API?
Create an account, generate an API key in the dashboard, and send it in the Authorization header as a Bearer token. API keys use the iu_live_ prefix and should be stored as secrets.
What does the upload endpoint accept?
Send multipart/form-data to POST /api/upload with one file. Optional fields include expiration, password, view_limit, folder, custom_slug, and custom_expires_at, subject to plan availability.
What does a successful API response contain?
The JSON response includes the slug, validated file details, dimensions, expiration data, share URL, direct URL, HTML, BBCode and Markdown embeds, upload source, and current API quota information.
What are the API upload limits?
Free accounts receive 10 API or MCP uploads per month and Starter accounts receive 50. Pro and Business accounts have no monthly upload count cap. A per-key ceiling of 60 uploads per minute and plan-specific storage and file-size limits still apply.
Can I use the same account with MCP tools?
Yes. The REST API and the imageupload.io MCP server use the same API key and account limits. MCP adds structured tools for uploading, listing, inspecting, organizing, and deleting images.
Keep exploring
Move from overview to implementation, or connect API uploads to the same browser workflows.
Make the first authenticated upload.
Create a free account, generate a Bearer API key, and use the documentation to ship a client that handles quotas and retries correctly.