API local

La API local expone JPGBoost como un servicio HTTP/JSON en tu máquina. Te permite controlar la importación, los ajustes y la exportación desde cualquier lenguaje capaz de enviar una solicitud HTTP.

Activar la API

La API está desactivada por defecto. Se activa en unos segundos:

1. Abre Ajustes (⌘,) y luego la pestaña API local.
2. Marca la casilla de activación. El servidor arranca de inmediato.
3. Ajusta el puerto si es necesario. El valor por defecto es 51823.
4. Copia el token de autenticación que aparece justo debajo. Un botón permite regenerarlo en cualquier momento.

Autenticación

Cada solicitud debe llevar la cabecera Authorization con tu token. Sin ella, o con un token no válido, la API responde 401.

TOKEN="<token mostrado en Ajustes>"
BASE="http://127.0.0.1:51823/v1"

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

Referencia de rutas

Todas las rutas llevan el prefijo /v1 y devuelven JSON estructurado: tamaño antes y después, ratio de compresión, y el posible error de cada archivo.

Ejemplos paso a paso

Consultar el estado actual

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

Importar archivos

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/ru/ta/a/imagen1.png", "/ru/ta/a/imagen2.jpg"]}' \
  "$BASE/import"

Cambiar la calidad y el formato

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 80, "format": "webp"}' \
  "$BASE/settings"

Listar las imágenes actuales

La respuesta indica, para cada imagen, su identificador, su estado, su tamaño antes y después, su ratio y el posible error.

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/images"

Exportar el lote

La exportación espera a que termine cualquier compresión en curso antes de escribir los archivos. Este tiempo de espera se puede ajustar con waitTimeoutSeconds, fijado en 30 segundos por defecto.

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder": "/ru/ta/de/salida", "waitTimeoutSeconds": 30}' \
  "$BASE/export"

Vaciar la lista

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/clear"

Actuar sobre una imagen concreta

Cada imagen tiene un identificador, devuelto por /v1/images. Permite tratarla de forma individual.

# Calidad específica de una imagen
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 92}' \
  "$BASE/images/<id>/quality"

# Volver al ajuste global para esta imagen
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# Exportar una sola imagen a una ruta concreta
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/ru/ta/de/salida/foto.webp"}' \
  "$BASE/images/<id>/export"

# Retirar una imagen del lote
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Perfiles de exportación vía la API

La API expone la misma lista de perfiles que la interfaz. Consulta la guía Perfiles de exportación para conocer la regla de prioridad. En JPGBoost Free, el límite de un solo perfil también se aplica aquí: POST /v1/profiles rechaza la creación de un segundo perfil, pero sigue aceptando sobrescribir el perfil existente con el mismo nombre.

# Crear o reemplazar un perfil (mismo nombre = sobrescritura)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/ru/ta/de/salida"}' \
  "$BASE/profiles"

# Listar los perfiles
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Eliminar un perfil (el espacio se convierte en %20 en la URL)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# Aplicar un perfil a los ajustes globales
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# Exportar a la carpeta del perfil, sin volver a indicar "folder"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

Comprobar que todo funciona

Dos scripts se incluyen dentro de la aplicación, en Contents/Resources. Ejecútalos con JPGBoost abierto y la API activada. Piden el token por teclado, salvo que la variable de entorno TOKEN ya esté definida, lo que permite encadenarlos en una integración continua.

Batería de comprobaciones

Comprueba la autenticación, el enrutado y la validación de parámetros, con una salida ✓/✗. Solo lectura por defecto; si se le pasa una imagen, realiza además un ciclo real de importación y exportación.

SCRIPTS=/Applications/JPGBoost.app/Contents/Resources

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /ru/ta/a/imagen.png

Recorrido guiado

Recorre paso a paso la secuencia completa descrita más arriba de forma legible, desde el rechazo sin token hasta la exportación final, pasando por el estado, la importación, los ajustes y la lista.

"$SCRIPTS/local_api_demo.sh" /ru/ta/a/imagen.png

Seguridad y privacidad

• El servidor solo escucha en la interfaz de bucle local (127.0.0.1), lo que significa que solo es accesible desde tu Mac. Nunca está expuesto a internet.
• Ninguna imagen viaja por internet. La API solo controla el motor de compresión local.
• El token se genera en tu máquina. Regenéralo si crees que ha podido divulgarse, por ejemplo tras pegarlo en un script compartido.
• Desactiva la API cuando no la uses: ese es su estado por defecto.