API PER SVILUPPATORI · BETA PUBBLICA

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:

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

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.

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

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}

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.

response
{"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.

response
{
  "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:

response
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}
  • 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 429 senza 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 429 rispetta Retry-After. Con 5xx o un errore di rete, riprova aumentando la pausa (1 s, 2 s, 4 s…). Per gli altri errori 4xx, riprovare non serve: correggi la richiesta.
  • Interroga con ?wait=55 invece 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.

Ottieni la tua chiave API

Specifiche, esempi, nodo