1What it is and who it is for
The API lets your programs upload photos to IMGpx and get the same links as the site gives: the photo page, a direct link, a thumbnail, BB code and HTML. Photos only — formats and file size are the same as when you upload on the site.
Address: https://api.imgpx.com/v1 — HTTPS only. Answers are JSON.
2How to get a key
1. Sign up and confirm your e-mail. 2. Open Settings → API. 3. Tick «My project is non-commercial» and press «Create a key». The key is shown once — save it right away.
The key goes only in the header: Authorization: Bearer YOUR_KEY. A key in the address (?key=) or in the body is refused — this keeps it out of server logs and browser history. Never put the key into a page that visitors see: requests to the API from web pages in a browser are not allowed.
3Limits
| Free | |
|---|---|
| Photos per month | 1,000 |
| Photos per day | 100 |
| Requests per minute | 30 |
| «My photos» list through the API | the last 1,000 |
| File size and formats | as when you upload on the site |
| Keys | 1 |
The month and the day follow your time zone (Settings → Time zone). A deleted photo does not give the upload back. What is left — in GET /v1/me and in the headers: X-Upload-Month-Remaining, X-Upload-Day-Remaining; requests per minute — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
4Uploading a photo
POST /v1/upload — a file (multipart/form-data) or base64 in the image field. POST only.
# curl curl -X POST https://api.imgpx.com/v1/upload \ -H "Authorization: Bearer YOUR_KEY" \ -F "[email protected]"
# Python import requests r = requests.post("https://api.imgpx.com/v1/upload", headers={"Authorization": "Bearer YOUR_KEY"}, files={"image": open("photo.jpg", "rb")}) print(r.json()["data"]["url"])
# base64 (PHP) $ch = curl_init('https://api.imgpx.com/v1/upload'); curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_KEY'], CURLOPT_POSTFIELDS => ['image' => base64_encode(file_get_contents('photo.jpg'))]]); $answer = json_decode(curl_exec($ch), true);
| Parameter | Description |
|---|---|
image | a file or base64 (required). Links to photos are not accepted. |
name | file name (optional) |
expiration | auto-deletion after N seconds: from 60 to 15,552,000 (180 days). Without it the photo is kept as usual. |
private | 1 — a private file only you can see (if private files are available to you) |
5The answer
{
"success": true,
"status": 200,
"data": {
"id": "aB3dE7kLm2Qx",
"page": "https://imgpx.com/Xy7Kp2Lm",
"url": "https://imgpx.com/aB3dE7kLm2Qx.jpg",
"thumb": "https://imgpx.com/thumbnail/aB3dE7kLm2Qx.webp",
"width": 1920, "height": 1080, "size": 284120, "format": "jpg",
"private": false, "expires_at": null,
"bbcode": "[url=…][img]…[/img][/url]", "bbcode_thumb": …,
"html": "<a href=…><img src=… /></a>", "html_thumb": …, "markdown": …,
"delete_url": "https://api.imgpx.com/v1/delete/aB3dE7kLm2Qx/…"
}
}The photo format may change exactly as on the site: for example PNG becomes WebP when that is on in your profile. delete_url deletes the photo without a key — do not publish it.
6My photos and deleting
| Method | What it does |
|---|---|
GET /v1/files?page=1&per_page=50 | your photos, newest first (up to 100 per page; the last 1,000) |
GET /v1/files/{id} | one photo |
DELETE /v1/files/{id} | delete a photo |
delete_url | the link from the upload answer — opens a page with a «Delete» button (for ShareX) |
GET /v1/me | your limits, what is used and when it renews |
The API never shows or deletes someone else's photos: the answer is 404 as if there were no such photo.
7Errors
{ "success": false, "status": 429, "error": { "code": "limit_day", "message": "…" } }| Code | Meaning |
|---|---|
| 400 | bad request: no photo, wrong base64 or expiration, a key in the address |
| 401 | no key or a wrong key |
| 403 | the API is off for your account, the key is revoked or HTTPS is needed |
| 404 | photo not found |
| 413 | the file is too large |
| 415 | not a photo, or this format is not available to you |
| 429 | a limit is reached — retry after the time in the Retry-After header |
Many wrong keys from one address — it loses access to the API for an hour. A key that gets very many errors in a row (a script stuck in a loop, for example) is switched off automatically — you get a message in the bell.
8ShareX
Download the ready settings file and open it twice — ShareX adds IMGpx as an upload service. Then in ShareX: Destinations → Custom uploader settings → Headers, replace YOUR_KEY with your key.
9API rules
- Personal and non-commercial projects only. For commercial use — contact us.
- The same rules as for the site: Terms of use, the section «What you may not upload».
- Never give your key to others or publish it. Lost or exposed — revoke it in your profile and make a new one.
- For breaking the rules or overloading the service the key is switched off without notice.

