API di MegaPotato
Ingrandisci le foto dal tuo codice con lo stesso modello e gli stessi prezzi in patatine del sito. Due richieste: invia una foto, poi recupera il risultato. Nel nostro confronto di ottobre 2026 tra 18 strumenti di ingrandimento con IA, il modello è arrivato primo ed era il più economico tra i migliori.
In questa pagina
Guida rapida
Crea una chiave nella pagina del tuo account, inseriscila nella variabile d'ambiente MEGAPOTATO_API_KEY ed esegui:
# 1. Invia una foto
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. Aspetta il risultato (il server tiene aperta la richiesta fino a 55 s)
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):
"""Una chiamata API. Riprova per gli errori temporanei (429, 5xx, rete), si ferma per tutti gli altri."""
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: # altri 4xx: correggi la richiesta, riprovare non serve
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")
# Byte, non un file aperto: ogni tentativo deve inviare di nuovo l'intera foto.
photo = open("photo.jpg", "rb").read()
job = call("POST", "/upscale", headers={"Idempotency-Key": "photo-001"},
files={"file": ("photo.jpg", photo)}, data={"upscale": "4"})
# Leggi sempre l'elaborazione almeno una volta: un caricamento ripetuto potrebbe essere già completato e solo GET include 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"])// Salva come upscale.mjs ed esegui con 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))
// Una chiamata API. Riprova per gli errori temporanei (429, 5xx, rete), si ferma per tutti gli altri.
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) // errore di rete: riprova
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 })
// Leggi sempre l'elaborazione almeno una volta: un caricamento ripetuto potrebbe essere già completato e solo GET include 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)Prova senza chiave
Senza account né chiave: invia una foto a /v1/try e interroga /v1/try/{id}. È un'elaborazione reale sullo stesso modello; cost_chips indica il costo con una chiave, ma non viene addebitato nulla. Le elaborazioni di prova vanno in coda dopo tutte quelle con chiave, quindi possono richiedere più tempo quando il servizio è occupato. La prova ha un budget limitato: 429 significa che devi aspettare il tempo indicato da Retry-After o ottenere una chiave; 403 significa che non è disponibile. Al momento non disponibile. Usa una chiave di test o una chiave API dalla pagina del tuo account.
# 1. Invia una foto (senza account né chiave)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}
# 2. Aspetta il risultato (il server tiene aperta la richiesta fino a 55 s)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}Chiavi di test
Vuoi configurare tutto prima di acquistare patatine? Ogni account che ha effettuato l'accesso può creare una chiave di test (mp_test_…) dalla pagina dell'account. Segue l'intero flusso: i file vengono verificati e il prezzo calcolato come con una chiave di produzione, ma non viene eseguita né addebitata alcuna elaborazione. Ogni richiesta restituisce completed con un'immagine di esempio sia in result_url che in result_jpeg_url; jpeg_status è sempre ready, con o senza jpeg=true. Riprovare con lo stesso Idempotency-Key e la stessa foto restituisce lo stesso ID di elaborazione; il riutilizzo della chiave per una foto diversa viene rifiutato (422) solo con le chiavi di produzione. Passa a una chiave di produzione quando è tutto pronto. Le chiavi di produzione si sbloccano con il primo pacchetto di patatine.
Autenticazione
Invia la chiave in ogni richiesta nell'header Authorization: Bearer mp_live_…. Le chiavi vengono mostrate solo alla creazione; noi conserviamo solo un hash. Tienile sul server, mai in un'app mobile, una pagina web o un repository. Se una chiave viene esposta, revocala dalla pagina dell'account: smetterà subito di funzionare.
Verifica il prezzo — POST /v1/quote
Invia dimensioni iniziali e fattore per ottenere il prezzo. Nessun caricamento né addebito.
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}Ingrandisci una foto — POST /v1/upscale
Form multipart con file (PNG, JPG, WEBP e HEIC, fino a 40 MB) e upscale: 1 (Rifinisci, stesse dimensioni), 2, 4 o 8. Il lato lungo può arrivare a 6 000 px nell'originale e a 16 400 px nel risultato. Per foto grandi, scegli un fattore più basso.
{"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}cost_chips viene subito riservato sul saldo e addebitato quando la foto è pronta. Se l'elaborazione fallisce, le patatine tornano automaticamente sul saldo.
L'opzione jpeg=true aggiunge al PNG un JPEG a piena risoluzione (qualità 92, senza sottocampionamento cromatico), senza costi aggiuntivi. Un PNG 16K senza perdita di qualità può pesare diverse centinaia di MB; il JPEG dello stesso risultato pesa di solito molto meno. L'elaborazione include quindi result_jpeg_url e jpeg_status. Riutilizzare un Idempotency-Key con una foto, un valore upscale o jpeg diversi restituisce 422.
Ottieni il risultato — GET /v1/jobs/{id}
Aggiungi ?wait=55: il server tiene aperta la richiesta fino al termine dell'elaborazione o per un massimo di 55 secondi. Di solito basta una sola chiamata.
La maggior parte delle foto è pronta in pochi secondi. Quando la domanda aumenta, attiviamo più risorse: le prime richieste possono richiedere un paio di minuti, poi tutto torna a piena velocità. Continua a interrogare con ?wait=55, non serve gestire casi particolari.
{
"id": "6f6f4c1e-…",
"status": "completed", // queued → running → completed | failed
"result_url": "https://…", // PNG; link valido per circa un'ora, senza bisogno di header di autenticazione
"error": null, // il motivo in caso di errore, con «le patatine sono state rimborsate»
"upscale": 4,
"created_at": "2026-09-15T10:00:00Z",
"eta_seconds": null, // una stima durante l'attesa o l'elaborazione
"result_jpeg_url": "https://…", // con jpeg=true: il JPEG a piena risoluzione, stesse regole di result_url
"jpeg_status": "ready" // null senza jpeg=true; pending → ready | unavailable
}Recupera di nuovo i dati dell’elaborazione per ottenere un result_url aggiornato. I risultati restano disponibili per 90 giorni.
jpeg_status è pending quando l'elaborazione è in coda o in corso, ready quando result_jpeg_url è disponibile e unavailable se è terminata senza JPEG (il PNG viene comunque fornito), è fallita o è scaduta. Senza jpeg=true entrambi i campi sono null. Fanno eccezione le chiavi di test: entrambi gli URL contengono l'immagine di esempio e jpeg_status è sempre ready.
Un'elaborazione completed può ancora indicare pending mentre il JPEG viene caricato. Di solito bastano pochi secondi, in rari casi fino a circa un'ora: result_url funziona già e una nuova interrogazione restituisce result_jpeg_url (o unavailable se il JPEG non arriva).
Errori
Tutti gli errori hanno la stessa struttura:
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}- 400 · invalid_request_errorImpossibile decodificare l'immagine, oppure le dimensioni superano i limiti.
- 401 · authentication_errorLa chiave manca, è errata o è stata revocata.
- 402 · insufficient_creditsPatatine insufficienti per questa foto: il messaggio indica quante ne servono.
- 404 · invalid_request_errorElaborazione inesistente o non tua.
- 413 · invalid_request_errorIl file supera il limite di caricamento.
- 415 · invalid_request_errorFormato immagine non supportato.
- 422 · invalid_request_errorValore upscale o jpeg non valido, file mancante o Idempotency-Key riutilizzato con una foto, upscale o jpeg diversi.
- 429 · rate_limit_errorTroppe richieste o troppe foto in elaborazione contemporaneamente. Rispetta Retry-After.
- 422 · content_not_allowedIl nostro controllo automatico dei contenuti ha bloccato l'immagine (vedi le Condizioni). Nessun addebito.
- 429 · spend_limit_reachedLimite di spesa API giornaliero raggiunto. Si azzera alle 00:00 UTC.
- 500 · server_errorErrore nostro. Riprova, usando lo stesso Idempotency-Key per i caricamenti.
- 503 · service_unavailableAl momento non possiamo accettare immagini. Nessun addebito; riprova dopo il tempo indicato da Retry-After.
| HTTP | type | Quando |
|---|---|---|
| 400 | invalid_request_error | Impossibile decodificare l'immagine, oppure le dimensioni superano i limiti. |
| 401 | authentication_error | La chiave manca, è errata o è stata revocata. |
| 402 | insufficient_credits | Patatine insufficienti per questa foto: il messaggio indica quante ne servono. |
| 404 | invalid_request_error | Elaborazione inesistente o non tua. |
| 413 | invalid_request_error | Il file supera il limite di caricamento. |
| 415 | invalid_request_error | Formato immagine non supportato. |
| 422 | invalid_request_error | Valore upscale o jpeg non valido, file mancante o Idempotency-Key riutilizzato con una foto, upscale o jpeg diversi. |
| 429 | rate_limit_error | Troppe richieste o troppe foto in elaborazione contemporaneamente. Rispetta Retry-After. |
| 422 | content_not_allowed | Il nostro controllo automatico dei contenuti ha bloccato l'immagine (vedi le Condizioni). Nessun addebito. |
| 429 | spend_limit_reached | Limite di spesa API giornaliero raggiunto. Si azzera alle 00:00 UTC. |
| 500 | server_error | Errore nostro. Riprova, usando lo stesso Idempotency-Key per i caricamenti. |
| 503 | service_unavailable | Al momento non possiamo accettare immagini. Nessun addebito; riprova dopo il tempo indicato da Retry-After. |
Limiti
- Fino a 10 foto in elaborazione contemporaneamente per account. Oltre questo limite, un nuovo caricamento restituisce
429senza addebiti. - Fino a 100 caricamenti al minuto per chiave; le richieste di stato hanno limiti più alti.
- Un limite di spesa API giornaliero (giorno UTC) impedisce che una chiave esposta esaurisca il saldo. Il valore predefinito è 5 000 patatine al giorno. Puoi abbassarlo dalla pagina dell'account.
Prezzi
A parità di foto e fattore, l'API costa esattamente quanto il sito e usa lo stesso saldo di patatine. Il prezzo cresce con le dimensioni del risultato: una foto da 1 MP a ×4 costa circa 2 patatine, una foto da telefono da 12 MP a ×2 circa 5 patatine. Le patatine costano $0.033–0.05 ciascuna, in base al pacchetto. Verifica qualsiasi dimensione con /v1/quote; le elaborazioni fallite vengono rimborsate automaticamente. Acquista le patatine nella pagina dei prezzi: non scadono mai.
Nuovi tentativi
- Invia sempre un
Idempotency-Key(fino a 128 caratteri, univoco per foto) con i caricamenti. Ripetere la richiesta con la stessa chiave restituisce la stessa elaborazione e addebita una sola volta: puoi quindi riprovare senza rischi dopo un timeout. - Con
429rispettaRetry-After. Con5xxo un errore di rete, riprova aumentando la pausa (1 s, 2 s, 4 s…). Per gli altri errori4xx, riprovare non serve: correggi la richiesta. - Interroga con
?wait=55invece di fare una chiamata al secondo.
Beta e versioni
L'API è in beta pubblica: non c'è ancora una garanzia di disponibilità e ti avviseremo via email delle modifiche previste. In /v1 aggiungiamo solo elementi, come nuovi campi o tipi di errore: ignora i campi che non conosci. Le modifiche incompatibili arriveranno con /v2, annunciate con almeno 90 giorni di anticipo.
Uso consentito
I risultati sono tuoi. Usa l'API solo per immagini che hai il diritto di elaborare. Non usarla per contenuti illegali, contenuti sessuali che coinvolgono minori o immagini intime di persone senza il loro consenso. Gli account che violano queste regole o le Condizioni vengono bloccati. Segnala gli abusi a abuse@megapotato.app; per domande, scrivi a support@megapotato.app.
Specifiche, esempi, nodo
- Specifica OpenAPI 3.1 — l'API /v1 in formato leggibile dalle macchine
- Questa documentazione in Markdown — la stessa documentazione in testo semplice, per strumenti e assistenti
- Esempi di codice su GitHub — curl, Python e Node.js, pronti da eseguire
- Nodo ComfyUI — la stessa API come nodo in ComfyUI Manager (codice su GitHub: MegaPotato-AI/comfyui-megapotato)
- Confronto tra 18 strumenti di ingrandimento con IA — confronto del modello con dati aperti (CC BY 4.0)
- llms.txt — il sito in una pagina per i modelli linguistici; /llms-full.txt contiene il testo completo