Documentación para desarrolladores

Guía rápida

Comprime tu primera imagen en 30 segundos: crea una clave de API en la consola y luego envía una solicitud.

El resultado se devuelve mediante un enlace privado cifrado al que solo tú, el titular de la clave, puedes acceder: las imágenes se usan únicamente para esta compresión, cifradas todo el tiempo, nunca filtradas y nunca usadas para entrenamiento ni ningún otro fin.

Autenticación

• HTTP Basic (compatible con las API de compresión populares): usuario fijo a api, la contraseña es tu clave de API — Authorization: Basic base64("api:KEY")
• Bearer (recomendado para la capa nativa): Authorization: Bearer KEY

Los prefijos de las claves son mp_live_ (producción) y mp_test_ (sandbox); el servidor almacena solo un hash de la clave, y la clave completa se muestra solo una vez en la creación. Cada cuenta puede tener hasta 5 claves. Los fallos de autenticación siempre devuelven 401 sin distinguir la causa (para evitar la enumeración).

POST /shrink Comprimir una imagen

El cuerpo de la solicitud es una de dos opciones: una imagen binaria en bruto (PNG / JPEG / WebP / HEIC / GIF / BMP / TIFF / AVIF), o JSON especificando una URL de origen (solo direcciones http/https públicas, tiempo de espera de descarga de 10 segundos). Cuando no se especifica un formato de salida, se mantiene el formato original: PNG / JPEG / WebP / GIF / TIFF / AVIF se generan en su formato original (AVIF→AVIF, TIFF→TIFF); HEIC se convierte a JPEG; BMP, que no se puede comprimir en su propio formato, se convierte a PNG. GIF se optimiza sin pérdidas por defecto (sigue siendo GIF), y también se puede convertir a WebP para ahorrar más.

Si tiene éxito, devuelve 201 Created, con cabeceras de respuesta que incluyen Location (la dirección del resultado) y Compression-Count (imágenes facturadas este mes):

GET /output/{id} Descargar el resultado

Requiere autenticación; devuelve el binario del resultado comprimido. Los resultados se sirven mediante un enlace privado cifrado; una vez que el enlace caduca, devuelve 404 OutputExpired, y puedes volver a comprimir para obtenerlo de nuevo. Volver a descargar el mismo resultado no se factura.

POST /output/{id} Operaciones derivadas

Ejecuta resize / convert / preserve sobre un resultado comprimido; cada salida derivada cuenta como 1 imagen:

• resize.method: scale (proporcional por un lado) / fit (encajar por completo) / cover (recortar para rellenar, actualmente recorte centrado)
• convert.type: convertir entre image/webp, image/png e image/jpeg
• preserve: conservar los metadatos copyright / creation / location

POST /v1/compress Compresión síncrona (capa nativa)

Una sola solicitud devuelve directamente el binario del resultado comprimido, ahorrando un viaje de ida y vuelta: práctico para CI:

• quality: smart (por defecto) / high / extreme / 1-100
• format: keep (mantener el formato original) / webp
• Cabeceras de respuesta: X-Input-Size / X-Output-Size / X-Ratio / Compression-Count

GET /v1/usage Consulta de uso

Devuelve el recuento de este mes, la cuota gratuita restante y el saldo restante de paquetes de crédito: idéntico a la consola:

Cuotas y límites de tasa

• Tasa: 10 sol/s por clave, ráfaga 20 (token bucket); superarlo devuelve 429 + Retry-After
• Concurrencia: tareas en curso por clave <= 20
• Cuota mensual gratuita: 500 imágenes/mes/cuenta; una vez agotada y sin pago registrado, devuelve 429 AccountLimitReached
• Por archivo: 5 MB gratis; 80 MB de pago; personalizable para empresas
• Píxeles: <= 100 megapíxeles; superarlo devuelve 422 ImageTooComplex

Cabeceras de respuesta en todos los endpoints medidos: Compression-Count, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Facturación

• POST /shrink con éxito (201): cuenta como 1 imagen
• POST /v1/compress con éxito (200): cuenta como 1 imagen
• GET /output/{id} nueva descarga: no se factura
• POST /output/{id} operación derivada con éxito: cuenta como 1 imagen cada vez
• 4xx / 5xx, bloqueos del filtrado de contenido y fallos de descarga de URL: no se facturan; en un reintento con éxito solo cuenta la llamada correcta

Orden de descuento: cuota mensual del plan → paquetes de crédito (el comprado primero se usa primero, nunca caducan). De prepago, sin factura mensual por uso: una vez agotada la cuota se pausa, y comprar un paquete de crédito la restaura.

Integración con IA / Skill

MiniPic ofrece una Agent Skill oficial (minipic-compress): una vez instalada, dile a cualquier agente de IA que admita el estándar abierto Anthropic Agent Skills (Claude Code / Cursor / Codex CLI / Copilot CLI, etc.) algo como "comprime las imágenes de esta carpeta" y llamará automáticamente a la API de MiniPic para comprimir, convertir a WebP, procesar por lotes e informar de la tasa de compresión, sin necesidad de escribir curl ni lógica de reintentos a mano.

Instalación

Elige una de las siguientes (tres opciones):

Para otros agentes que admitan el estándar Agent Skills (Cursor / Codex CLI / Copilot CLI, etc.), sigue su documentación para colocar el directorio minipic-compress/ en la ruta de skills correspondiente.

Configura tu clave de API

La clave se lee solo desde una variable de entorno y nunca se escribe en duro ni se muestra por pantalla. Tras crear una clave en la consola, configúrala en tu entorno:

Alcance y ejemplos de activación

La Skill se activa automáticamente cuando expresas intenciones como:

• "Comprime esta imagen / las imágenes de esta carpeta"
• "Convierte hero.png a WebP y déjalo lo más pequeño posible"
• "Estas imágenes son demasiado grandes: optimízalas por lotes antes de empaquetar y dime cuánto ahorré"

Capacidades: compresión de un solo archivo / lote de carpeta / URL remota, conversión entre PNG·JPEG·WebP·GIF, selección de preajuste de calidad (smart / high / extreme), cálculo e informe automáticos del porcentaje de ahorro, y reintento automático con retroceso ante la limitación de tasa 429.

Extensión de VS Code

La extensión oficial MiniPic Image Compression te permite comprimir las imágenes del espacio de trabajo directamente en tu editor, sin escribir curl a mano, con la potencia del motor propio de MiniPic. Admite PNG / JPEG / WebP / GIF / AVIF / TIFF y puede convertir de formato mientras comprime (por ejemplo, a WebP / AVIF para ahorrar más), y funciona en VS Code, Cursor y otros editores compatibles.

Instalación

Elige una de las siguientes:

• En el panel de Extensiones de VS Code (⇧⌘X) busca MiniPic y haz clic en Instalar;
• o ejecuta ext install minipic.minipic-vscode desde la paleta de comandos;
• o visita la página de la extensión en Visual Studio Marketplace y haz clic en Instalar.

Configura tu clave de API

Tras crear una clave (que empieza por mp_live_) en la consola, ejecuta MiniPic: Set API Key desde la paleta de comandos (⇧⌘P) y pégala. La clave se almacena de forma segura en VS Code SecretStorage y nunca se escribe en configuración en texto plano ni se sincroniza mediante settings.json.

Cómo usarla

• Comprimir con clic derecho: selecciona imágenes o carpetas en el Explorador (individuales, multiselección o todo el directorio de forma recursiva) → clic derecho en MiniPic: Compress Images para comprimir en el sitio usando los ajustes actuales de calidad y formato.
• Convertir a WebP y actualizar las referencias: clic derecho en MiniPic: Convert to WebP and Update References para convertir a WebP mientras se actualizan automáticamente las referencias a esa imagen en todo tu espacio de trabajo.
• Compresión automática: cuando está activada, vigila las imágenes nuevas/modificadas del espacio de trabajo y las comprime automáticamente (desactivada por defecto, ya que consume cuota); actívala desde la barra de estado o con MiniPic: Toggle Auto-Compress.
• Ver el uso: ejecuta MiniPic: View Usage para ver el recuento comprimido de este mes, el saldo gratuito y la estimación de uso: idéntico a la consola.

Ajustes habituales

Códigos de error

El cuerpo del error sigue la convención de las API de compresión populares: {"error": "código", "message": "descripción legible"}; los campos solo se añaden, nunca se eliminan.