MegaPotato API
Upscale photos from your own code with the same model and the same chip prices as the site. Two requests: send a photo, then pick up the result. In our October 2026 benchmark of 18 AI upscalers the model came first and was the cheapest of the leaders.
On this page
Quickstart
Create a key on your account page, put it in the MEGAPOTATO_API_KEY environment variable, and run:
# 1. Send a photo
curl https://megapotato.app/v1/upscale \
-H "Authorization: Bearer $MEGAPOTATO_API_KEY" \
-H "Idempotency-Key: photo-001" \
-F file=@photo.jpg \
-F upscale=4
# β {"id": "6f6f4c1e-β¦", "status": "queued", "upscale": 4, "cost_chips": 2}
# 2. Wait for it (the server holds the request up to 55 s)
curl "https://megapotato.app/v1/jobs/6f6f4c1e-β¦?wait=55" \
-H "Authorization: Bearer $MEGAPOTATO_API_KEY"
# β {"status": "completed", "result_url": "https://β¦", β¦}import os, sys, time, requests
API = "https://megapotato.app/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MEGAPOTATO_API_KEY']}"}
def call(method, path, headers=None, **kwargs):
"""One API call. Retries what can succeed later (429, 5xx, network), stops on everything else."""
for attempt in range(8):
try:
r = requests.request(method, f"{API}{path}", headers={**HEADERS, **(headers or {})}, timeout=70, **kwargs)
except (requests.ConnectionError, requests.Timeout):
time.sleep(2 ** attempt)
continue
if r.status_code == 429 or r.status_code >= 500:
time.sleep(float(r.headers.get("Retry-After", 2 ** attempt)))
continue
if not r.ok: # other 4xx: fix the request, retrying won't help
err = r.json()["error"]
sys.exit(f"{r.status_code} {err['type']}: {err['message']}")
return r.json()
sys.exit("gave up after repeated temporary errors")
# Bytes, not an open file: every retry must send the whole photo again.
photo = open("photo.jpg", "rb").read()
job = call("POST", "/upscale", headers={"Idempotency-Key": "photo-001"},
files={"file": ("photo.jpg", photo)}, data={"upscale": "4"})
# Always read the job at least once: a retried upload may already be finished, and only GET carries result_url / error.
while True:
job = call("GET", f"/jobs/{job['id']}", params={"wait": 55})
if job["status"] in ("completed", "failed"):
break
if job["status"] == "completed":
result = requests.get(job["result_url"], timeout=120)
result.raise_for_status()
open("photo_x4.png", "wb").write(result.content)
else:
print(job["error"])// Save as upscale.mjs and run with Node 18+: node upscale.mjs
import { readFile } from "node:fs/promises"
const API = "https://megapotato.app/v1"
const headers = { Authorization: `Bearer ${process.env.MEGAPOTATO_API_KEY}` }
const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
// One API call. Retries what can succeed later (429, 5xx, network), stops on everything else.
async function call(path, init = {}) {
for (let attempt = 0; attempt < 8; attempt++) {
let res
try {
res = await fetch(`${API}${path}`, { ...init, headers: { ...headers, ...init.headers } })
} catch {
await sleep(2 ** attempt * 1000) // network error: try again
continue
}
if (res.status === 429 || res.status >= 500) {
await sleep(Number(res.headers.get("retry-after") ?? 2 ** attempt) * 1000)
continue
}
const body = await res.json()
if (!res.ok) throw new Error(`${res.status} ${body.error.type}: ${body.error.message}`)
return body
}
throw new Error("gave up after repeated temporary errors")
}
const form = new FormData()
form.append("file", new Blob([await readFile("photo.jpg")]), "photo.jpg")
form.append("upscale", "4")
const { id } = await call("/upscale", { method: "POST", headers: { "Idempotency-Key": "photo-001" }, body: form })
// Always read the job at least once: a retried upload may already be finished, and only GET carries result_url / error.
let job
do {
job = await call(`/jobs/${id}?wait=55`)
} while (job.status !== "completed" && job.status !== "failed")
console.log(job.status === "completed" ? job.result_url : job.error)Try it without a key
No account and no key: send a photo to /v1/try and poll /v1/try/{id}. It is a real job on the same model; cost_chips is what a key would pay, and nothing is charged. Trial jobs queue behind every keyed job, so they can wait longer when the service is busy. The trial is budgeted, so a 429 means wait for Retry-After or get a key, and a 403 means it is closed. Closed right now; use a test key or an API key from your account page.
# 1. Send a photo (no account, no key)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# β {"id": "6f6f4c1e-β¦", "status": "queued", "upscale": 4, "cost_chips": 2}
# 2. Wait for it (the server holds the request up to 55 s)
curl "https://megapotato.app/v1/try/6f6f4c1e-β¦?wait=55"
# β {"status": "completed", "result_url": "https://β¦", β¦}Test keys
Want to wire things up before buying chips? Any signed-in account can create a test key (mp_test_β¦) on the account page. It goes through the whole flow β uploads are checked and priced exactly like with a live key β but nothing runs and nothing is charged: every job comes back completed with a sample image in both result_url and result_jpeg_url, and jpeg_status is always ready, whether jpeg=true was sent or not. A retry with the same Idempotency-Key and photo returns the same job id; reusing a key for a different photo is only rejected (422) on live keys. Switch to a live key when you're ready. Live keys unlock with your first chip pack.
Authentication
Send your key on every request in the Authorization header: Bearer mp_live_β¦. Keys are shown once when you create them; we store only a hash. Keep them on your server β never in a mobile app, a web page or a repository. If a key leaks, revoke it on your account page; it stops working immediately.
Check the price β POST /v1/quote
Send the input size and factor, get the price back. Nothing is uploaded or charged.
curl https://megapotato.app/v1/quote \
-H "Authorization: Bearer $MEGAPOTATO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"width": 4032, "height": 3024, "upscale": 2}'
# β {"cost_chips": 5, "output_width": 8064, "output_height": 6048, "upscale": 2}Upscale a photo β POST /v1/upscale
Multipart form with file (PNG, JPG, WEBP and HEIC, up to 40 MB) and upscale: 1 (refine, same size), 2, 4 or 8. The input can be up to 6Β 000 px on its long edge, and the result up to 16Β 400 px β pick a smaller factor for large photos.
{"id": "6f6f4c1e-β¦", "status": "queued", "upscale": 4, "cost_chips": 2}cost_chips is held from your balance right away and charged when the photo is done. If processing fails, the chips come back automatically.
Optional jpeg=true adds a full-size JPEG of the result (quality 92, no chroma subsampling) next to the PNG, at no extra cost. A lossless 16K PNG can weigh several hundred MB, the JPEG of the same result usually a small fraction of that. The job then carries result_jpeg_url and jpeg_status. An Idempotency-Key reused with a different photo, upscale or jpeg is a 422.
Get the result β GET /v1/jobs/{id}
Add ?wait=55 and the server holds the request until the job finishes or 55 seconds pass, whichever comes first β one call usually covers the whole job.
Most photos are back in seconds. When demand grows we bring more capacity online, and the first requests after that can take a couple of minutes β then everything runs at full speed. Keep polling with ?wait=55; there's nothing special to handle.
{
"id": "6f6f4c1e-β¦",
"status": "completed", // queued β running β completed | failed
"result_url": "https://β¦", // PNG; a link valid for about an hour, no auth header needed
"error": null, // the reason when failed, with "your chips were refunded"
"upscale": 4,
"created_at": "2026-09-15T10:00:00Z",
"eta_seconds": null, // an estimate while queued or running
"result_jpeg_url": "https://β¦", // with jpeg=true: the full-size JPEG, same rules as result_url
"jpeg_status": "ready" // null without jpeg=true; pending β ready | unavailable
}Fetch the job again for a fresh result_url. Results stay available for 90 days.
jpeg_status is pending while the job is queued or running, ready once result_jpeg_url is set, and unavailable when the job completed without a JPEG (the PNG is still delivered), failed or expired. Without jpeg=true both fields are null. Test keys are the exception: both URLs hold the sample image and jpeg_status is always ready.
A completed job can still read pending while its JPEG is being uploaded β usually for seconds, in rare cases up to about an hour: result_url already works, and polling again brings result_jpeg_url (or unavailable if it never arrives).
Errors
Every error has the same shape:
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}- 400 Β· invalid_request_errorThe image can't be decoded, or its size is over the limits.
- 401 Β· authentication_errorThe key is missing, wrong or revoked.
- 402 Β· insufficient_creditsNot enough chips for this photo β the message says how many are needed.
- 404 Β· invalid_request_errorNo such job (or not yours).
- 413 Β· invalid_request_errorThe file is larger than the upload limit.
- 415 Β· invalid_request_errorUnsupported image format.
- 422 Β· invalid_request_errorBad upscale or jpeg value, missing file, or an Idempotency-Key reused for a different photo, upscale or jpeg.
- 429 Β· rate_limit_errorToo many requests, or too many photos in progress at once. Honor Retry-After.
- 422 Β· content_not_allowedOur automated content check blocked the image (see the Terms). Nothing was charged.
- 429 Β· spend_limit_reachedToday's API spending limit is reached. Resets at 00:00 UTC.
- 500 Β· server_errorOur fault. Retry β with the same Idempotency-Key for uploads.
- 503 Β· service_unavailableWe can't accept images right now. Nothing was charged; retry after Retry-After.
| HTTP | type | When |
|---|---|---|
| 400 | invalid_request_error | The image can't be decoded, or its size is over the limits. |
| 401 | authentication_error | The key is missing, wrong or revoked. |
| 402 | insufficient_credits | Not enough chips for this photo β the message says how many are needed. |
| 404 | invalid_request_error | No such job (or not yours). |
| 413 | invalid_request_error | The file is larger than the upload limit. |
| 415 | invalid_request_error | Unsupported image format. |
| 422 | invalid_request_error | Bad upscale or jpeg value, missing file, or an Idempotency-Key reused for a different photo, upscale or jpeg. |
| 429 | rate_limit_error | Too many requests, or too many photos in progress at once. Honor Retry-After. |
| 422 | content_not_allowed | Our automated content check blocked the image (see the Terms). Nothing was charged. |
| 429 | spend_limit_reached | Today's API spending limit is reached. Resets at 00:00 UTC. |
| 500 | server_error | Our fault. Retry β with the same Idempotency-Key for uploads. |
| 503 | service_unavailable | We can't accept images right now. Nothing was charged; retry after Retry-After. |
Limits
- Up to 10 photos in progress at once per account. Past that, a new upload gets
429and nothing is charged. - Up to 100 uploads per minute per key; status requests are more generous.
- A daily spending limit through the API (UTC day), so a leaked key can't drain your balance β by default 5Β 000 chips a day. You can set a lower limit on your account page.
Pricing
The API costs exactly what the site costs for the same photo and factor, paid from the same chip balance. The price grows with the size of the result: a 1 MP photo at Γ4 costs about 2 chips, a 12 MP phone photo at Γ2 about 5 chips. Chips cost $0.033β0.05 each depending on the pack. Check any size with /v1/quote; a failed job is refunded automatically. Buy chips on the pricing page; they never expire.
Retries
- Always send an
Idempotency-Key(up to 128 characters, unique per photo) with uploads. Repeating the request with the same key returns the same job and charges once β so a timeout is always safe to retry. - On
429wait forRetry-After. On5xxor a network error, retry with a growing pause (1 s, 2 s, 4 sβ¦). Other4xxerrors won't succeed on retry β fix the request. - Poll with
?wait=55instead of calling every second.
Beta & versioning
The API is in public beta: there is no uptime guarantee yet, and we'll tell you by email about planned changes. Within /v1 we only add things β new fields, new error types β so ignore fields you don't know. Anything that would break an integration will ship as /v2, announced at least 90 days ahead.
Acceptable use
Results belong to you. Use the API only for images you have the right to process. It must not be used for illegal content, sexual content involving minors, or intimate images of anyone without their consent. Accounts that break these rules or the Terms are blocked. Report abuse to abuse@megapotato.app; questions go to support@megapotato.app.
Spec, examples, node
- OpenAPI 3.1 specification β the /v1 API as a machine-readable spec
- This documentation as Markdown β the same reference in plain text, for tools and assistants
- Code examples on GitHub β curl, Python and Node.js, ready to run
- ComfyUI node β the same API as a node in ComfyUI Manager (source on GitHub: MegaPotato-AI/comfyui-megapotato)
- Benchmark of 18 AI upscalers β how the model compares, with open data (CC BY 4.0)
- llms.txt β the site in one page for language models; /llms-full.txt has the full text