MegaPotato API
在自己的代码中放大照片,使用与网站相同的模型和薯片价格。只需两次请求:上传照片,再获取结果。在我们于 2026 年 10 月开展的 18 款 AI 图片放大工具评测中,该模型排名第一,也是领先产品中价格最低的。
快速入门
在账户页面创建密钥,存入 MEGAPOTATO_API_KEY 环境变量,然后运行:
# 1. 上传照片
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. 等待结果(服务器最多保持请求 55 秒)
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):
"""一次 API 调用。遇到可恢复的错误(429、5xx、网络错误)会重试,其他情况则停止。"""
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: # 其他 4xx:请修正请求,重试无法解决
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")
# 使用字节数据,而非已打开的文件:每次重试都必须重新发送完整照片。
photo = open("photo.jpg", "rb").read()
job = call("POST", "/upscale", headers={"Idempotency-Key": "photo-001"},
files={"file": ("photo.jpg", photo)}, data={"upscale": "4"})
# 务必至少查询一次任务:重试上传时,任务可能已完成,只有 GET 会返回 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"])// 保存为 upscale.mjs,使用 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))
// 一次 API 调用。遇到可恢复的错误(429、5xx、网络错误)会重试,其他情况则停止。
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) // 网络错误:请重试
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 })
// 务必至少查询一次任务:重试上传时,任务可能已完成,只有 GET 会返回 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)免密钥试用
无需账户或密钥:将照片发送至 /v1/try,然后轮询 /v1/try/{id}。这会用相同模型实际处理照片;cost_chips 表示使用密钥时的费用,试用不扣费。试用任务排在所有密钥任务之后,繁忙时等待可能更久。试用有预算限制,收到 429 时请按 Retry-After 等待或获取密钥,403 则表示试用已关闭。目前未开放,请使用测试密钥或账户页面中的 API 密钥。
# 1. 上传照片(无需账户或密钥)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}
# 2. 等待结果(服务器最多保持请求 55 秒)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}测试密钥
想先接入,再购买薯片?所有已登录账户都能在账户页面创建测试密钥(mp_test_…)。测试密钥可走完整个流程,上传校验和计价与正式密钥完全相同,但不会实际处理图片或扣费:每个任务都返回 completed,result_url 和 result_jpeg_url 均为示例图片,jpeg_status 始终为 ready,无论是否传入 jpeg=true。使用相同 Idempotency-Key 和照片重试,会返回相同的任务 ID;同一个幂等键用于不同照片时,只有正式密钥会拒绝请求(422)。准备就绪后,换成正式密钥即可。首次购买薯片包后即可创建正式密钥。
身份验证
每次请求都需在 Authorization 请求头中发送密钥:Bearer mp_live_…。密钥仅在创建时显示一次,我们只保存其哈希值。请将密钥保存在服务器上,切勿放入移动应用、网页或代码仓库。如果密钥泄露,请在账户页面撤销,撤销后立即失效。
查询价格 — POST /v1/quote
发送原图尺寸和放大倍率,即可获取价格。无需上传图片,也不扣费。
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}放大照片 — POST /v1/upscale
使用 multipart 表单,包含 file(PNG、JPG、WEBP 和 HEIC,最大 40 MB)和 upscale:1(精修,尺寸不变)、2、4 或 8。原图长边最多 6 000 px,结果长边最多 16 400 px;大图请选择较小倍率。
{"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}cost_chips 对应的薯片会立即从余额中冻结,照片处理完成后扣除。若处理失败,薯片自动退还。
可选参数 jpeg=true 可在 PNG 之外免费生成全尺寸 JPEG(质量 92,无色度下采样)。无损 16K PNG 可能有数百 MB,同一结果的 JPEG 通常小得多。此时任务会包含 result_jpeg_url 和 jpeg_status。同一个 Idempotency-Key 搭配不同的照片、upscale 或 jpeg 会返回 422。
获取结果 — GET /v1/jobs/{id}
添加 ?wait=55,服务器会保持请求,直到任务完成或满 55 秒,以先到者为准。通常一次调用就能等到结果。
大多数照片几秒内就能处理完成。需求增加时,我们会扩充算力,扩容后的首批请求可能需要几分钟,之后便会恢复全速。继续使用 ?wait=55 轮询即可,无需特殊处理。
{
"id": "6f6f4c1e-…",
"status": "completed", // queued → running → completed | failed
"result_url": "https://…", // PNG;链接有效期约一小时,无需身份验证请求头
"error": null, // 失败原因,包含“薯片已退还”
"upscale": 4,
"created_at": "2026-09-15T10:00:00Z",
"eta_seconds": null, // 排队或运行时的预计耗时
"result_jpeg_url": "https://…", // 传入 jpeg=true 时:全尺寸 JPEG,规则与 result_url 相同
"jpeg_status": "ready" // 未传入 jpeg=true 时为 null;pending → ready | unavailable
}再次获取任务即可获得新的 result_url。结果保留 90 天。
任务排队或运行时,jpeg_status 为 pending;result_jpeg_url 就绪后变为 ready;任务完成但未生成 JPEG(仍提供 PNG)、失败或过期时为 unavailable。未传入 jpeg=true 时,两字段均为 null。测试密钥除外:两个 URL 都指向示例图片,jpeg_status 始终为 ready。
任务状态已为 completed 时,JPEG 可能仍在上传,显示 pending,通常持续几秒,少数情况可达约一小时。此时 result_url 已可用,继续轮询即可获取 result_jpeg_url(若始终未就绪,则返回 unavailable)。
错误
所有错误均采用相同格式:
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}- 400 · invalid_request_error图片无法解码,或尺寸超出限制。
- 401 · authentication_error密钥缺失、错误或已撤销。
- 402 · insufficient_credits薯片不足,错误信息中会说明需要多少薯片。
- 404 · invalid_request_error任务不存在,或不属于你。
- 413 · invalid_request_error文件大小超出上传限制。
- 415 · invalid_request_error不支持此图片格式。
- 422 · invalid_request_errorupscale 或 jpeg 值无效、缺少文件,或同一个 Idempotency-Key 搭配了不同的照片、upscale 或 jpeg。
- 429 · rate_limit_error请求过多,或同时处理的照片过多。请按 Retry-After 等待。
- 422 · content_not_allowed我们的自动内容检查拦截了此图片(详见服务条款),未扣费。
- 429 · spend_limit_reached今日 API 消耗已达上限,将在 UTC 00:00 重置。
- 500 · server_error我们这边出了问题,请重试;重新上传时请使用相同的 Idempotency-Key。
- 503 · service_unavailable暂时无法接收图片,未扣费。请按 Retry-After 等待后重试。
| HTTP | type | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | 图片无法解码,或尺寸超出限制。 |
| 401 | authentication_error | 密钥缺失、错误或已撤销。 |
| 402 | insufficient_credits | 薯片不足,错误信息中会说明需要多少薯片。 |
| 404 | invalid_request_error | 任务不存在,或不属于你。 |
| 413 | invalid_request_error | 文件大小超出上传限制。 |
| 415 | invalid_request_error | 不支持此图片格式。 |
| 422 | invalid_request_error | upscale 或 jpeg 值无效、缺少文件,或同一个 Idempotency-Key 搭配了不同的照片、upscale 或 jpeg。 |
| 429 | rate_limit_error | 请求过多,或同时处理的照片过多。请按 Retry-After 等待。 |
| 422 | content_not_allowed | 我们的自动内容检查拦截了此图片(详见服务条款),未扣费。 |
| 429 | spend_limit_reached | 今日 API 消耗已达上限,将在 UTC 00:00 重置。 |
| 500 | server_error | 我们这边出了问题,请重试;重新上传时请使用相同的 Idempotency-Key。 |
| 503 | service_unavailable | 暂时无法接收图片,未扣费。请按 Retry-After 等待后重试。 |
限制
- 每个账户最多同时处理 10 张照片。超出后,新上传会返回
429,不扣费。 - 每个密钥每分钟最多上传 100 次,状态查询限制更宽松。
- API 设有每日消耗上限(按 UTC 日计算),避免密钥泄露耗尽余额;默认上限为 每天 5 000 片薯片。你可以在账户页面设置更低的上限。
价格
同一张照片、同一倍率,API 与网站价格完全一致,共用薯片余额。输出尺寸越大,费用越高:1 MP 照片放大 ×4 约需 2 片薯片,12 MP 手机照片放大 ×2 约需 5 片薯片。薯片单价因薯片包而异,为 $0.033–0.05。可用 /v1/quote 查询任意尺寸的价格,任务失败会自动退还薯片。前往价格页面购买薯片,永不过期。
重试
- 上传时请始终发送
Idempotency-Key(最多 128 个字符,每张照片唯一)。使用相同幂等键重复请求,会返回同一任务,只扣费一次,因此超时后可放心重试。 - 遇到
429,请按Retry-After等待。遇到5xx或网络错误,请逐步延长重试间隔(1 秒、2 秒、4 秒…)。其他4xx错误无法靠重试解决,请修正请求。 - 请使用
?wait=55轮询,无需每秒查询。
公测与版本管理
API 目前处于公测阶段,暂不提供可用性保证,计划内变更会通过邮件通知。在 /v1 内只会新增字段、错误类型等内容,因此请忽略未知字段。任何不兼容的变更都会通过 /v2 发布,并至少提前 90 天通知。
使用规范
处理结果归你所有。请仅使用 API 处理你有权处理的图片。禁止用于违法内容、涉及未成年人的色情内容,或未经本人同意的私密影像。违反这些规则或服务条款的账户将被封禁。举报滥用请联系 abuse@megapotato.app;其他问题请联系 support@megapotato.app。
规范、示例与节点
- OpenAPI 3.1 规范 — /v1 API 的机器可读规范
- 本文档的 Markdown 版 — 供工具和助手使用的纯文本版参考文档
- GitHub 代码示例 — 可直接运行的 curl、Python 和 Node.js 示例
- ComfyUI 节点 — ComfyUI Manager 中调用同一 API 的节点(GitHub 源码:MegaPotato-AI/comfyui-megapotato)
- 18 款 AI 图片放大工具评测 — 模型对比评测,附开放数据(CC BY 4.0)
- llms.txt — 面向语言模型的网站单页介绍,完整文本见 /llms-full.txt