API PARA DESARROLLADORES · BETA PÚBLICA

API de MegaPotato

Amplía fotos desde tu código con el mismo modelo y los mismos precios en chips que en la web. Dos peticiones: envía una foto y recoge el resultado. En nuestra comparativa de 18 ampliadores con IA de octubre de 2026, el modelo quedó primero y fue el más económico entre los mejores.

En esta página

Inicio rápido

Crea una clave en tu cuenta, guárdala en la variable de entorno MEGAPOTATO_API_KEY y ejecuta:

shell
# 1. Envía 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. Espera el resultado (el servidor mantiene la petición hasta 55 s)
curl "https://megapotato.app/v1/jobs/6f6f4c1e-…?wait=55" \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY"
# → {"status": "completed", "result_url": "https://…", …}

Pruébala sin clave

Sin cuenta ni clave: envía una foto a /v1/try y consulta /v1/try/{id}. Es una tarea real con el mismo modelo; cost_chips indica lo que se pagaría con una clave, pero no se cobra nada. Las tareas de prueba van detrás de todas las tareas con clave, así que pueden tardar más cuando hay mucha demanda. La prueba tiene un presupuesto limitado: un 429 indica que debes esperar el tiempo de Retry-After u obtener una clave; un 403 indica que está cerrada. Ahora está cerrado; usa una clave de prueba o una clave API de tu cuenta.

shell
# 1. Envía una foto (sin cuenta ni clave)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

# 2. Espera el resultado (el servidor mantiene la petición hasta 55 s)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}

Claves de prueba

¿Quieres preparar la integración antes de comprar chips? Cualquier cuenta con sesión iniciada puede crear una clave de prueba (mp_test_…) desde su página de cuenta. Recorre todo el flujo: valida los archivos y calcula su precio igual que con una clave de producción, pero no procesa ni cobra nada. Cada tarea devuelve completed con una imagen de ejemplo en result_url y result_jpeg_url, y jpeg_status siempre es ready, se haya enviado jpeg=true o no. Reintentar con la misma Idempotency-Key y foto devuelve el mismo ID de tarea; reutilizarla para otra foto solo se rechaza (422) con claves de producción. Cambia a una clave de producción cuando tengas todo listo. Las claves de producción se activan con tu primer paquete de chips.

Autenticación

Envía tu clave en cada petición en la cabecera Authorization: Bearer mp_live_…. Las claves solo se muestran al crearlas; solo guardamos un hash. Guárdalas en tu servidor, nunca en una app para teléfonos, una web o un repositorio. Si una clave se filtra, revócala desde tu cuenta; dejará de funcionar al instante.

Consultar el precio — POST /v1/quote

Envía el tamaño original y el factor de ampliación para obtener el precio. No se sube ni se cobra nada.

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}

Ampliar una foto — POST /v1/upscale

Formulario multipart con file (PNG, JPG, WEBP y HEIC, hasta 40 MB) y upscale: 1 (refinar, mismo tamaño), 2, 4 o 8. El original admite hasta 6 000 px en el lado más largo y el resultado hasta 16 400 px. Elige un factor menor para fotos grandes.

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

cost_chips se retiene de tu saldo al instante y se cobra cuando la foto está lista. Si el proceso falla, los chips se devuelven automáticamente.

La opción jpeg=true añade un JPEG del resultado a tamaño completo (calidad 92, sin submuestreo de crominancia) junto al PNG, sin coste extra. Un PNG 16K sin pérdida puede pesar cientos de MB; el JPEG del mismo resultado suele pesar mucho menos. La tarea incluye entonces result_jpeg_url y jpeg_status. Reutilizar una Idempotency-Key con otra foto u otro valor de upscale o jpeg devuelve 422.

Obtener el resultado — GET /v1/jobs/{id}

Añade ?wait=55 y el servidor mantendrá la petición abierta hasta que la tarea termine o pasen 55 segundos, lo que ocurra primero. Una llamada suele cubrir la tarea completa.

La mayoría de las fotos están listas en segundos. Cuando aumenta la demanda, activamos más capacidad y las primeras peticiones pueden tardar un par de minutos; después todo funciona a plena velocidad. Sigue consultando con ?wait=55; no necesitas hacer nada especial.

response
{
  "id": "6f6f4c1e-…",
  "status": "completed",          // queued → running → completed | failed
  "result_url": "https://…",      // PNG; enlace válido durante una hora aproximadamente, sin cabecera de autenticación
  "error": null,                  // el motivo del fallo, con «se han devuelto tus chips»
  "upscale": 4,
  "created_at": "2026-09-15T10:00:00Z",
  "eta_seconds": null,            // una estimación mientras está en cola o en curso
  "result_jpeg_url": "https://…", // con jpeg=true: el JPEG a tamaño completo, con las mismas reglas que result_url
  "jpeg_status": "ready"          // null sin jpeg=true; pending → ready | unavailable
}

Consulta la tarea de nuevo para obtener una result_url nueva. Los resultados están disponibles durante 90 días.

jpeg_status es pending mientras la tarea está en cola o en curso, ready cuando se asigna result_jpeg_url y unavailable si la tarea terminó sin JPEG (el PNG se entrega igualmente), falló o caducó. Sin jpeg=true, ambos campos son null. Las claves de prueba son la excepción: ambas URL contienen la imagen de ejemplo y jpeg_status siempre es ready.

Una tarea completed aún puede indicar pending mientras se sube su JPEG: suele tardar segundos y, en casos excepcionales, hasta una hora. result_url ya funciona, y una nueva consulta devuelve result_jpeg_url (o unavailable si nunca llega).

Errores

Todos los errores tienen la misma estructura:

response
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}
  • 400 · invalid_request_error
    No se puede decodificar la imagen o su tamaño supera los límites.
  • 401 · authentication_error
    Falta la clave, es incorrecta o se ha revocado.
  • 402 · insufficient_credits
    No tienes suficientes chips para esta foto. El mensaje indica cuántos necesitas.
  • 404 · invalid_request_error
    La tarea no existe o no te pertenece.
  • 413 · invalid_request_error
    El archivo supera el límite de subida.
  • 415 · invalid_request_error
    Formato de imagen no compatible.
  • 422 · invalid_request_error
    Valor de upscale o jpeg incorrecto, falta el archivo o se reutilizó una Idempotency-Key con otra foto u otro valor de upscale o jpeg.
  • 429 · rate_limit_error
    Demasiadas peticiones o demasiadas fotos en curso a la vez. Respeta Retry-After.
  • 422 · content_not_allowed
    Nuestra comprobación automática de contenido ha bloqueado la imagen (consulta las condiciones). No se ha cobrado nada.
  • 429 · spend_limit_reached
    Has alcanzado el límite de gasto diario de la API. Se restablece a las 00:00 UTC.
  • 500 · server_error
    El fallo es nuestro. Reintenta con la misma Idempotency-Key si estás subiendo un archivo.
  • 503 · service_unavailable
    Ahora no podemos aceptar imágenes. No se ha cobrado nada; reintenta tras el tiempo de Retry-After.

Límites

  • Hasta 10 fotos en curso a la vez por cuenta. Si se supera ese límite, las nuevas subidas devuelven 429 y no se cobra nada.
  • Hasta 100 subidas por minuto y clave; las consultas de estado tienen un límite más amplio.
  • Un límite de gasto diario por API (día UTC) evita que una clave filtrada agote tu saldo: por defecto, 5 000 chips al día. Puedes establecer un límite menor en tu cuenta.

Precios

La API cuesta exactamente lo mismo que la web para la misma foto y factor, y usa el mismo saldo de chips. El precio aumenta con el tamaño del resultado: una foto de 1 MP a ×4 cuesta unos 2 chips, y una foto de teléfono de 12 MP a ×2, unos 5 chips. Cada chip cuesta $0.033–0.05 según el paquete. Consulta cualquier tamaño con /v1/quote; si una tarea falla, se reembolsa automáticamente. Compra chips en la página de precios; nunca caducan.

Reintentos

  • Envía siempre una Idempotency-Key (hasta 128 caracteres, única por foto) al subir archivos. Repetir la petición con la misma clave devuelve la misma tarea y cobra una sola vez, así que puedes reintentar sin riesgo si se agota el tiempo de espera.
  • Ante un 429, espera el tiempo de Retry-After. Ante un 5xx o un error de conexión, reintenta con pausas cada vez mayores (1 s, 2 s, 4 s…). Los demás errores 4xx no se resuelven reintentando: corrige la petición.
  • Consulta con ?wait=55 en lugar de hacer una llamada cada segundo.

Beta y versiones

La API está en beta pública: aún no garantizamos su disponibilidad y te avisaremos por email de los cambios previstos. En /v1 solo añadimos cosas, como campos y tipos de error nuevos, así que ignora los campos que no conozcas. Cualquier cambio incompatible con una integración llegará en /v2, con al menos 90 días de aviso.

Uso permitido

Los resultados son tuyos. Usa la API solo con imágenes que tengas derecho a procesar. No se permite contenido ilegal, contenido sexual con menores ni imágenes íntimas de personas sin su consentimiento. Las cuentas que incumplan estas reglas o las condiciones se bloquean. Denuncia abusos en abuse@megapotato.app; envía tus dudas a support@megapotato.app.

Obtener tu clave API

Especificación, ejemplos y nodo