MegaPotato API
웹사이트와 같은 모델, 같은 감자칩 요금으로 코드에서 직접 사진을 업스케일하세요. 사진을 보내고 결과를 받는 두 번의 요청이면 돼요. 2026년 10월에 진행한 AI 업스케일러 18종 벤치마크에서 1위를 기록했고, 상위권 중 가격도 가장 저렴했어요.
빠른 시작
계정 페이지에서 키를 만든 뒤 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"})
# 항상 작업을 한 번 이상 조회하세요. 재시도한 업로드는 이미 완료됐을 수 있고, result_url / error는 GET에만 포함돼요.
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 })
// 항상 작업을 한 번 이상 조회하세요. 재시도한 업로드는 이미 완료됐을 수 있고, result_url / error는 GET에만 포함돼요.
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=true 전송 여부와 관계없이 jpeg_status는 항상 ready예요. 같은 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
멀티파트 폼에 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가 포함돼요. 다른 사진, upscale 또는 jpeg 값에 Idempotency-Key를 재사용하면 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을 받아요. 끝내 JPEG가 생성되지 않으면 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 값이 올바르지 않거나, 파일이 없거나, 다른 사진·upscale·jpeg 값에 Idempotency-Key를 재사용했어요.
- 429 · rate_limit_error요청이 너무 많거나 동시에 처리 중인 사진이 너무 많아요. Retry-After만큼 기다려 주세요.
- 422 · content_not_allowed자동 콘텐츠 검사에서 이미지가 차단됐어요(이용약관 참고). 감자칩은 차감되지 않았어요.
- 429 · spend_limit_reached오늘의 API 사용 한도에 도달했어요. 00:00 UTC에 초기화돼요.
- 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 값이 올바르지 않거나, 파일이 없거나, 다른 사진·upscale·jpeg 값에 Idempotency-Key를 재사용했어요. |
| 429 | rate_limit_error | 요청이 너무 많거나 동시에 처리 중인 사진이 너무 많아요. Retry-After만큼 기다려 주세요. |
| 422 | content_not_allowed | 자동 콘텐츠 검사에서 이미지가 차단됐어요(이용약관 참고). 감자칩은 차감되지 않았어요. |
| 429 | spend_limit_reached | 오늘의 API 사용 한도에 도달했어요. 00:00 UTC에 초기화돼요. |
| 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 버전 — 도구와 AI 어시스턴트용 일반 텍스트 참조 문서
- GitHub 코드 예제 — 바로 실행할 수 있는 curl, Python, Node.js 예제
- ComfyUI 노드 — 같은 API를 쓰는 ComfyUI Manager 노드(GitHub 소스: MegaPotato-AI/comfyui-megapotato)
- AI 업스케일러 18종 벤치마크 — 공개 데이터(CC BY 4.0)로 보는 모델 성능 비교
- llms.txt — 언어 모델을 위한 사이트 한 페이지 요약. 전체 내용은 /llms-full.txt에 있어요