API DÉVELOPPEUR · BÊTA PUBLIQUE

API MegaPotato

Agrandissez vos photos depuis votre code, avec le même modèle et les mêmes prix en chips que sur le site. Deux requêtes : envoyer une photo, puis récupérer le résultat. Dans notre comparatif d’octobre 2026 de 18 outils d’agrandissement IA, le modèle est arrivé premier et était le moins cher parmi les meilleurs.

Sur cette page

Démarrage rapide

Créez une clé dans votre compte, placez-la dans la variable d’environnement MEGAPOTATO_API_KEY, puis exécutez :

shell
# 1. Envoyer une photo
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. Attendre (le serveur garde la requête ouverte jusqu’à 55 s)
curl "https://megapotato.app/v1/jobs/6f6f4c1e-…?wait=55" \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY"
# → {"status": "completed", "result_url": "https://…", …}

Essayer sans clé

Sans compte ni clé : envoyez une photo à /v1/try, puis interrogez /v1/try/{id}. Il s’agit d’un vrai traitement avec le même modèle. cost_chips indique le prix avec une clé, mais rien n’est débité. Les essais passent après tous les traitements avec clé et peuvent donc attendre plus longtemps en période d’affluence. Leur budget est limité : un code 429 signifie qu’il faut respecter Retry-After ou obtenir une clé ; un code 403 signifie que l’essai est fermé. Fermé pour le moment. Utilisez une clé de test ou une clé API depuis votre compte.

shell
# 1. Envoyer une photo (sans compte ni clé)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

# 2. Attendre (le serveur garde la requête ouverte jusqu’à 55 s)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}

Clés de test

Vous souhaitez préparer votre intégration avant d’acheter des chips ? Tout compte connecté peut créer une clé de test (mp_test_…) depuis la page du compte. Elle permet de tester tout le parcours : les fichiers sont vérifiés et leur prix calculé comme avec une clé de production, mais aucun traitement n’est exécuté ni facturé. Chaque tâche renvoie completed, avec une image d’exemple dans result_url et result_jpeg_url. Le champ jpeg_status vaut toujours ready, même sans jpeg=true. Renvoyer la même photo avec la même Idempotency-Key renvoie le même identifiant de tâche. Réutiliser cette clé pour une autre photo n’est rejeté (422) qu’avec une clé de production. Passez à une clé de production quand tout est prêt. Les clés de production sont accessibles dès l’achat de votre premier pack de chips.

Authentification

Envoyez votre clé à chaque requête dans l’en-tête Authorization : Bearer mp_live_…. Les clés ne s’affichent qu’une fois, à leur création ; nous ne stockons que leur empreinte. Gardez-les sur votre serveur, jamais dans une application mobile, une page web ou un dépôt. Si une clé est divulguée, révoquez-la depuis votre compte : elle cessera immédiatement de fonctionner.

Vérifier le prix — POST /v1/quote

Envoyez les dimensions d’origine et le facteur pour obtenir le prix. Aucun fichier envoyé, aucun débit.

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}

Agrandir une photo — POST /v1/upscale

Formulaire multipart avec file (PNG, JPG, WEBP et HEIC, jusqu’à 40 Mo) et upscale : 1 (Affiner, même taille), 2, 4 ou 8. Le côté le plus long peut mesurer jusqu’à 6 000 px pour l’original et 16 400 px pour le résultat. Choisissez un facteur plus faible pour les grandes photos.

response
{"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

cost_chips est réservé sur votre solde dès l’envoi, puis débité une fois la photo prête. Si le traitement échoue, les chips sont rendues automatiquement.

L’option jpeg=true ajoute gratuitement un JPEG en pleine résolution (qualité 92, sans sous-échantillonnage chromatique) au PNG. Un PNG 16K sans perte peut peser plusieurs centaines de Mo ; le JPEG du même résultat est généralement bien plus léger. La tâche contient alors result_jpeg_url et jpeg_status. Réutiliser une Idempotency-Key avec une autre photo ou une autre valeur de upscale ou jpeg renvoie 422.

Récupérer le résultat — GET /v1/jobs/{id}

Ajoutez ?wait=55 pour que le serveur garde la requête ouverte jusqu’à la fin du traitement ou pendant 55 secondes maximum. Un seul appel suffit généralement pour toute la tâche.

La plupart des photos sont prêtes en quelques secondes. En période d’affluence, nous ajoutons des ressources. Les premières requêtes peuvent alors prendre quelques minutes, avant un retour à pleine vitesse. Continuez à interroger avec ?wait=55 : aucune gestion particulière n’est nécessaire.

response
{
  "id": "6f6f4c1e-…",
  "status": "completed",          // queued → running → completed | failed
  "result_url": "https://…",      // PNG ; lien valable environ une heure, sans en-tête d’authentification
  "error": null,                  // la raison de l’échec, avec « vos chips ont été remboursées »
  "upscale": 4,
  "created_at": "2026-09-15T10:00:00Z",
  "eta_seconds": null,            // une estimation pendant l’attente ou le traitement
  "result_jpeg_url": "https://…", // avec jpeg=true : le JPEG en pleine résolution, mêmes règles que result_url
  "jpeg_status": "ready"          // null sans jpeg=true ; pending → ready | unavailable
}

Récupérez à nouveau la tâche pour obtenir un nouveau lien result_url. Les résultats restent disponibles 90 jours.

jpeg_status vaut pending pendant l’attente ou le traitement, ready quand result_jpeg_url est disponible et unavailable si la tâche est terminée sans JPEG (le PNG reste fourni), a échoué ou a expiré. Sans jpeg=true, les deux champs valent null. Exception pour les clés de test : les deux URL contiennent l’image d’exemple et jpeg_status vaut toujours ready.

Une tâche completed peut encore indiquer pending pendant l’envoi de son JPEG, généralement quelques secondes, rarement jusqu’à environ une heure. result_url fonctionne déjà. Interrogez à nouveau pour obtenir result_jpeg_url ou unavailable si le JPEG n’arrive pas.

Erreurs

Toutes les erreurs suivent ce format :

response
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}
  • 400 · invalid_request_error
    L’image ne peut pas être décodée ou ses dimensions dépassent les limites.
  • 401 · authentication_error
    La clé est absente, incorrecte ou révoquée.
  • 402 · insufficient_credits
    Pas assez de chips pour cette photo. Le message indique le nombre nécessaire.
  • 404 · invalid_request_error
    Cette tâche n’existe pas ou ne vous appartient pas.
  • 413 · invalid_request_error
    Le fichier dépasse la taille maximale autorisée.
  • 415 · invalid_request_error
    Format d’image non pris en charge.
  • 422 · invalid_request_error
    Valeur upscale ou jpeg incorrecte, fichier manquant ou Idempotency-Key réutilisée avec une autre photo ou une autre valeur upscale ou jpeg.
  • 429 · rate_limit_error
    Trop de requêtes ou de photos en cours. Respectez Retry-After.
  • 422 · content_not_allowed
    Notre vérification automatique du contenu a bloqué l’image (voir les Conditions d’utilisation). Aucun débit.
  • 429 · spend_limit_reached
    Plafond de dépenses API atteint pour aujourd’hui. Réinitialisation à 00:00 UTC.
  • 500 · server_error
    L’erreur vient de nous. Réessayez avec la même Idempotency-Key pour les envois.
  • 503 · service_unavailable
    Les envois d’images sont indisponibles pour le moment. Aucun débit ; réessayez après le délai Retry-After.

Limites

  • Jusqu’à 10 photos en cours par compte. Au-delà, tout nouvel envoi renvoie 429 sans aucun débit.
  • Jusqu’à 100 envois par minute et par clé. La limite est plus souple pour les requêtes de statut.
  • Un plafond de dépenses API par jour UTC empêche qu’une clé divulguée vide votre solde. Par défaut : 5 000 chips par jour. Vous pouvez le réduire depuis votre compte.

Tarifs

L’API coûte exactement le même prix que le site pour une même photo et un même facteur, avec le même solde de chips. Le prix augmente avec la taille du résultat : une photo de 1 MP en ×4 coûte environ 2 chips, une photo de téléphone de 12 MP en ×2 environ 5 chips. Une chips coûte $0.033–0.05 selon le pack. Vérifiez le prix de toute taille avec /v1/quote. Un traitement échoué est remboursé automatiquement. Achetez des chips sur la page Tarifs : elles n’expirent jamais.

Nouvelles tentatives

  • Envoyez toujours une Idempotency-Key (128 caractères maximum, unique par photo) avec vos fichiers. Répéter la requête avec la même clé renvoie la même tâche et ne facture qu’une fois. Vous pouvez donc réessayer sans risque après un délai d’attente dépassé.
  • En cas de 429, respectez Retry-After. En cas de 5xx ou d’erreur réseau, espacez les tentatives (1 s, 2 s, 4 s…). Pour les autres erreurs 4xx, réessayer ne suffit pas : corrigez la requête.
  • Interrogez avec ?wait=55 plutôt qu’une fois par seconde.

Bêta et versions

L’API est en bêta publique, sans garantie de disponibilité pour le moment. Les changements prévus vous seront annoncés par e-mail. Dans /v1, nous faisons uniquement des ajouts (champs, types d’erreurs) : ignorez les champs inconnus. Toute modification incompatible sera publiée dans /v2 et annoncée au moins 90 jours à l’avance.

Usages autorisés

Les résultats vous appartiennent. Utilisez l’API uniquement pour des images que vous avez le droit de traiter. Les contenus illégaux, les contenus sexuels impliquant des mineurs et les images intimes sans le consentement des personnes concernées sont interdits. Les comptes qui enfreignent ces règles ou les Conditions d’utilisation sont bloqués. Signalez les abus à abuse@megapotato.app et envoyez vos questions à support@megapotato.app.

Obtenir votre clé API

Spécification, exemples, nœud