개발자 API · 공개 베타

MegaPotato API

웹사이트와 같은 모델, 같은 감자칩 요금으로 코드에서 직접 사진을 업스케일하세요. 사진을 보내고 결과를 받는 두 번의 요청이면 돼요. 2026년 10월에 진행한 AI 업스케일러 18종 벤치마크에서 1위를 기록했고, 상위권 중 가격도 가장 저렴했어요.

목차

빠른 시작

계정 페이지에서 키를 만든 뒤 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=true 전송 여부와 관계없이 jpeg_status는 항상 ready예요. 같은 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

멀티파트 폼에 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가 포함돼요. 다른 사진, upscale 또는 jpeg 값에 Idempotency-Key를 재사용하면 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을 받아요. 끝내 JPEG가 생성되지 않으면 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 값이 올바르지 않거나, 파일이 없거나, 다른 사진·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으로 보내 주세요.

API 키 받기

명세, 예제, 노드