API MegaPotato
Phóng to ảnh ngay trong mã của bạn với cùng mô hình và giá tính bằng lát khoai chiên như trên web. Chỉ hai yêu cầu: gửi ảnh, rồi lấy kết quả. Trong thử nghiệm 18 công cụ phóng to ảnh AI vào tháng 10/2026 của chúng tôi, mô hình đứng đầu và có giá thấp nhất trong nhóm dẫn đầu.
Trên trang này
Bắt đầu nhanh
Tạo khóa trên trang tài khoản, đặt vào biến môi trường MEGAPOTATO_API_KEY rồi chạy:
# 1. Gửi ảnh
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. Chờ kết quả (máy chủ giữ yêu cầu tối đa 55 giây)
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):
"""Một lệnh gọi API. Thử lại các lỗi có thể hết sau đó (429, 5xx, mạng), dừng với các lỗi khác."""
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 khác: sửa yêu cầu, thử lại không giúp được
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")
# Dùng byte, không dùng tệp đang mở: mỗi lần thử lại phải gửi lại toàn bộ ảnh.
photo = open("photo.jpg", "rb").read()
job = call("POST", "/upscale", headers={"Idempotency-Key": "photo-001"},
files={"file": ("photo.jpg", photo)}, data={"upscale": "4"})
# Luôn đọc tác vụ ít nhất một lần: ảnh gửi lại có thể đã xử lý xong, và chỉ GET trả về 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"])// Lưu thành upscale.mjs rồi chạy với 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))
// Một lệnh gọi API. Thử lại các lỗi có thể hết sau đó (429, 5xx, mạng), dừng với các lỗi khác.
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) // lỗi mạng: thử lại
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 })
// Luôn đọc tác vụ ít nhất một lần: ảnh gửi lại có thể đã xử lý xong, và chỉ GET trả về 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)Thử không cần khóa
Không cần tài khoản hay khóa: gửi ảnh đến /v1/try rồi truy vấn định kỳ /v1/try/{id}. Đây là tác vụ thật trên cùng mô hình; cost_chips là phí nếu dùng khóa, còn bạn không bị tính phí. Tác vụ dùng thử xếp sau mọi tác vụ có khóa nên có thể chờ lâu hơn khi dịch vụ bận. Dùng thử có ngân sách giới hạn: 429 nghĩa là chờ theo Retry-After hoặc lấy khóa, còn 403 nghĩa là đang đóng. Hiện đang đóng; hãy dùng khóa thử nghiệm hoặc khóa API từ trang tài khoản.
# 1. Gửi ảnh (không cần tài khoản hay khóa)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}
# 2. Chờ kết quả (máy chủ giữ yêu cầu tối đa 55 giây)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}Khóa thử nghiệm
Muốn tích hợp trước khi mua lát khoai chiên? Mọi tài khoản đã đăng nhập đều có thể tạo khóa thử nghiệm (mp_test_…) trên trang tài khoản. Khóa chạy toàn bộ quy trình — ảnh tải lên được kiểm tra và tính giá như khóa thật — nhưng không xử lý ảnh và không thu phí: mọi tác vụ đều trả về completed với ảnh mẫu trong cả result_url và result_jpeg_url; jpeg_status luôn là ready dù có gửi jpeg=true hay không. Gửi lại cùng Idempotency-Key và ảnh sẽ trả về cùng mã tác vụ; dùng lại khóa cho ảnh khác chỉ bị từ chối (422) khi dùng khóa thật. Chuyển sang khóa thật khi bạn sẵn sàng. Khóa thật được mở khi bạn mua gói lát khoai chiên đầu tiên.
Xác thực
Gửi khóa trong header Authorization của mọi yêu cầu: Bearer mp_live_…. Khóa chỉ hiện một lần khi tạo; chúng tôi chỉ lưu giá trị băm. Giữ khóa trên máy chủ — đừng đặt trong ứng dụng di động, trang web hoặc kho mã. Nếu khóa bị lộ, hãy thu hồi trên trang tài khoản; khóa sẽ ngừng hoạt động ngay.
Kiểm tra giá — POST /v1/quote
Gửi kích thước đầu vào và hệ số phóng to để nhận giá. Không tải ảnh lên hay tính phí.
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}Phóng to ảnh — POST /v1/upscale
Biểu mẫu multipart gồm file (PNG, JPG, WEBP và HEIC, tối đa 40 MB) và upscale: 1 (chế độ Chi tiết, giữ nguyên kích thước), 2, 4 hoặc 8. Cạnh dài ảnh đầu vào tối đa 6 000 px, kết quả tối đa 16 400 px — chọn hệ số nhỏ hơn cho ảnh lớn.
{"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}cost_chips được giữ ngay từ số dư và trừ khi ảnh hoàn tất. Nếu xử lý lỗi, lát khoai chiên tự động được hoàn lại.
Tùy chọn jpeg=true thêm bản JPEG đủ kích thước của kết quả (chất lượng 92, không giảm mẫu màu) bên cạnh PNG, không tính thêm phí. PNG 16K không mất dữ liệu có thể nặng vài trăm MB, còn JPEG của cùng kết quả thường nhẹ hơn nhiều. Tác vụ khi đó có result_jpeg_url và jpeg_status. Dùng lại Idempotency-Key với ảnh, upscale hoặc jpeg khác sẽ trả về 422.
Lấy kết quả — GET /v1/jobs/{id}
Thêm ?wait=55 để máy chủ giữ yêu cầu đến khi tác vụ hoàn tất hoặc hết 55 giây, tùy điều kiện nào đến trước — thường chỉ cần gọi một lần cho cả tác vụ.
Hầu hết ảnh có kết quả trong vài giây. Khi nhu cầu tăng, chúng tôi bổ sung năng lực xử lý; những yêu cầu đầu tiên lúc đó có thể mất vài phút, sau đó mọi thứ sẽ chạy hết tốc độ. Cứ tiếp tục truy vấn với ?wait=55; không cần xử lý gì đặc biệt.
{
"id": "6f6f4c1e-…",
"status": "completed", // queued → running → completed | failed
"result_url": "https://…", // PNG; liên kết có hiệu lực khoảng một giờ, không cần header xác thực
"error": null, // lý do khi thất bại, kèm "lát khoai chiên của bạn đã được hoàn lại"
"upscale": 4,
"created_at": "2026-09-15T10:00:00Z",
"eta_seconds": null, // ước tính khi đang chờ hoặc chạy
"result_jpeg_url": "https://…", // với jpeg=true: JPEG đủ kích thước, cùng quy tắc như result_url
"jpeg_status": "ready" // null nếu không có jpeg=true; pending → ready | unavailable
}Truy vấn lại tác vụ để lấy result_url mới. Kết quả được lưu trong 90 ngày.
jpeg_status là pending khi tác vụ đang chờ hoặc chạy, ready khi có result_jpeg_url, và unavailable khi tác vụ hoàn tất mà không có JPEG (vẫn có PNG), bị lỗi hoặc hết hạn. Nếu không có jpeg=true, cả hai trường đều là null. Khóa thử nghiệm là ngoại lệ: cả hai URL đều chứa ảnh mẫu và jpeg_status luôn là ready.
Tác vụ completed vẫn có thể hiển thị pending khi JPEG đang được tải lên — thường vài giây, hiếm khi đến khoảng một giờ: result_url đã dùng được, truy vấn lại sẽ có result_jpeg_url (hoặc unavailable nếu không tạo được).
Lỗi
Mọi lỗi đều có cùng cấu trúc:
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}- 400 · invalid_request_errorKhông đọc được ảnh hoặc kích thước vượt giới hạn.
- 401 · authentication_errorKhóa bị thiếu, sai hoặc đã thu hồi.
- 402 · insufficient_creditsKhông đủ lát khoai chiên cho ảnh này — thông báo cho biết số lát khoai chiên cần dùng.
- 404 · invalid_request_errorKhông có tác vụ này (hoặc không phải của bạn).
- 413 · invalid_request_errorTệp vượt giới hạn tải lên.
- 415 · invalid_request_errorĐịnh dạng ảnh không được hỗ trợ.
- 422 · invalid_request_errorGiá trị upscale hoặc jpeg không hợp lệ, thiếu tệp hoặc Idempotency-Key được dùng lại với ảnh, upscale hay jpeg khác.
- 429 · rate_limit_errorQuá nhiều yêu cầu hoặc quá nhiều ảnh đang xử lý cùng lúc. Chờ theo Retry-After.
- 422 · content_not_allowedHệ thống kiểm tra nội dung tự động của chúng tôi đã chặn ảnh (xem Điều khoản). Không bị tính phí.
- 429 · spend_limit_reachedĐã đạt giới hạn chi tiêu API hôm nay. Đặt lại lúc 00:00 UTC.
- 500 · server_errorLỗi từ phía chúng tôi. Hãy thử lại — dùng cùng Idempotency-Key khi tải lên.
- 503 · service_unavailableHiện chúng tôi chưa thể nhận ảnh. Không bị tính phí; hãy thử lại sau thời gian ghi trong Retry-After.
| HTTP | type | Khi nào |
|---|---|---|
| 400 | invalid_request_error | Không đọc được ảnh hoặc kích thước vượt giới hạn. |
| 401 | authentication_error | Khóa bị thiếu, sai hoặc đã thu hồi. |
| 402 | insufficient_credits | Không đủ lát khoai chiên cho ảnh này — thông báo cho biết số lát khoai chiên cần dùng. |
| 404 | invalid_request_error | Không có tác vụ này (hoặc không phải của bạn). |
| 413 | invalid_request_error | Tệp vượt giới hạn tải lên. |
| 415 | invalid_request_error | Định dạng ảnh không được hỗ trợ. |
| 422 | invalid_request_error | Giá trị upscale hoặc jpeg không hợp lệ, thiếu tệp hoặc Idempotency-Key được dùng lại với ảnh, upscale hay jpeg khác. |
| 429 | rate_limit_error | Quá nhiều yêu cầu hoặc quá nhiều ảnh đang xử lý cùng lúc. Chờ theo Retry-After. |
| 422 | content_not_allowed | Hệ thống kiểm tra nội dung tự động của chúng tôi đã chặn ảnh (xem Điều khoản). Không bị tính phí. |
| 429 | spend_limit_reached | Đã đạt giới hạn chi tiêu API hôm nay. Đặt lại lúc 00:00 UTC. |
| 500 | server_error | Lỗi từ phía chúng tôi. Hãy thử lại — dùng cùng Idempotency-Key khi tải lên. |
| 503 | service_unavailable | Hiện chúng tôi chưa thể nhận ảnh. Không bị tính phí; hãy thử lại sau thời gian ghi trong Retry-After. |
Giới hạn
- Mỗi tài khoản xử lý đồng thời tối đa 10 ảnh. Vượt mức này, ảnh tải lên mới sẽ nhận
429và không bị tính phí. - Mỗi khóa tải lên tối đa 100 ảnh mỗi phút; yêu cầu kiểm tra trạng thái có giới hạn cao hơn.
- Giới hạn chi tiêu qua API mỗi ngày (theo UTC) giúp khóa bị lộ không dùng hết số dư — mặc định là 5 000 lát khoai chiên mỗi ngày. Bạn có thể đặt mức thấp hơn trên trang tài khoản.
Bảng giá
API có giá đúng như trên web cho cùng ảnh và hệ số phóng to, trừ từ cùng số dư lát khoai chiên. Giá tăng theo kích thước kết quả: ảnh 1 MP ở ×4 tốn khoảng 2 lát khoai chiên, ảnh điện thoại 12 MP ở ×2 khoảng 5 lát khoai chiên. Mỗi lát khoai chiên có giá $0.033–0.05 tùy gói. Kiểm tra giá mọi kích thước bằng /v1/quote; tác vụ lỗi được tự động hoàn lát khoai chiên. Mua lát khoai chiên trên trang bảng giá; lát khoai chiên không bao giờ hết hạn.
Thử lại
- Luôn gửi
Idempotency-Key(tối đa 128 ký tự, riêng cho mỗi ảnh) khi tải lên. Gửi lại yêu cầu với cùng khóa sẽ trả về cùng tác vụ và chỉ tính phí một lần — nên bạn có thể yên tâm thử lại khi hết thời gian chờ. - Với
429, chờ theoRetry-After. Với5xxhoặc lỗi mạng, thử lại với thời gian chờ tăng dần (1 giây, 2 giây, 4 giây…). Các lỗi4xxkhác sẽ không hết khi thử lại — hãy sửa yêu cầu. - Truy vấn định kỳ với
?wait=55thay vì gọi mỗi giây.
Beta & phiên bản
API đang ở bản beta công khai: chưa có cam kết về thời gian hoạt động và chúng tôi sẽ báo qua email về các thay đổi dự kiến. Trong /v1, chúng tôi chỉ bổ sung trường và loại lỗi mới — hãy bỏ qua các trường chưa biết. Thay đổi làm gián đoạn tích hợp sẽ được đưa vào /v2, báo trước ít nhất 90 ngày.
Quy định sử dụng
Kết quả thuộc về bạn. Chỉ dùng API cho ảnh bạn có quyền xử lý. Không được dùng cho nội dung bất hợp pháp, nội dung tình dục liên quan đến người chưa thành niên hoặc ảnh riêng tư nhạy cảm của người khác khi chưa có sự đồng ý. Tài khoản vi phạm các quy định này hoặc Điều khoản sẽ bị chặn. Báo cáo lạm dụng đến abuse@megapotato.app; gửi câu hỏi đến support@megapotato.app.
Đặc tả, ví dụ, node
- Đặc tả OpenAPI 3.1 — API /v1 dưới dạng đặc tả máy có thể đọc
- Tài liệu này ở dạng Markdown — cùng tài liệu tham khảo ở dạng văn bản thuần, dành cho công cụ và trợ lý
- Mã ví dụ trên GitHub — curl, Python và Node.js, có thể chạy ngay
- Node ComfyUI — cùng API dưới dạng node trong ComfyUI Manager (mã nguồn trên GitHub: MegaPotato-AI/comfyui-megapotato)
- Thử nghiệm 18 công cụ phóng to ảnh AI — kết quả so sánh mô hình, kèm dữ liệu mở (CC BY 4.0)
- llms.txt — tóm tắt trang web trong một trang cho mô hình ngôn ngữ; /llms-full.txt có nội dung đầy đủ