开发者 API · 公测

MegaPotato API

在自己的代码中放大照片,使用与网站相同的模型和薯片价格。只需两次请求:上传照片,再获取结果。在我们于 2026 年 10 月开展的 18 款 AI 图片放大工具评测中,该模型排名第一,也是领先产品中价格最低的。

本页目录

快速入门

在账户页面创建密钥,存入 MEGAPOTATO_API_KEY 环境变量,然后运行:

shell
# 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://…", …}

免密钥试用

无需账户或密钥:将照片发送至 /v1/try,然后轮询 /v1/try/{id}。这会用相同模型实际处理照片;cost_chips 表示使用密钥时的费用,试用不扣费。试用任务排在所有密钥任务之后,繁忙时等待可能更久。试用有预算限制,收到 429 时请按 Retry-After 等待或获取密钥,403 则表示试用已关闭。目前未开放,请使用测试密钥或账户页面中的 API 密钥。

shell
# 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

发送原图尺寸和放大倍率,即可获取价格。无需上传图片,也不扣费。

shell
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;大图请选择较小倍率。

response
{"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 轮询即可,无需特殊处理。

response
{
  "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)。

错误

所有错误均采用相同格式:

response
{"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_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。

获取 API 密钥

规范、示例与节点