API local

A API local expõe o JPGBoost como um serviço HTTP/JSON na sua máquina. Permite-lhe controlar a importação, os ajustes e a exportação a partir de qualquer linguagem capaz de enviar um pedido HTTP.

Ativar a API

A API está desativada por padrão. Ativa-se em segundos:

1. Abra Ajustes (⌘,) e depois o separador API local.
2. Marque a caixa de ativação. O servidor arranca de imediato.
3. Ajuste a porta se necessário. O valor padrão é 51823.
4. Copie o token de autenticação apresentado logo abaixo. Um botão permite regenerá-lo a qualquer momento.

Autenticação

Cada pedido tem de levar o cabeçalho Authorization com o seu token. Sem ele, ou com um token inválido, a API responde 401.

TOKEN="<token apresentado em Ajustes>"
BASE="http://127.0.0.1:51823/v1"

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

Referência de rotas

Todas as rotas têm o prefixo /v1 e devolvem JSON estruturado: tamanho antes e depois, proporção de compressão, e o possível erro de cada arquivo.

Exemplos passo a passo

Consultar o estado atual

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

Importar arquivos

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/caminho/para/imagem1.png", "/caminho/para/imagem2.jpg"]}' \
  "$BASE/import"

Alterar a qualidade e o formato

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

Listar as imagens atuais

A resposta indica, para cada imagem, o seu identificador, o seu estado, o seu tamanho antes e depois, a sua proporção e o possível erro.

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

Exportar o lote

A exportação aguarda que qualquer compressão em curso termine antes de escrever os arquivos. Este tempo de espera é configurável com waitTimeoutSeconds, fixado em 30 segundos por padrão.

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

Esvaziar a lista

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

Atuar sobre uma imagem específica

Cada imagem tem um identificador, devolvido por /v1/images. Permite tratá-la de forma individual.

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

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

# Exportar uma única imagem para um caminho específico
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/caminho/de/saida/foto.webp"}' \
  "$BASE/images/<id>/export"

# Remover uma imagem do lote
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Perfis de exportação via a API

A API expõe a mesma lista de perfis que a interface. Consulte o guia Perfis de exportação para conhecer a regra de prioridade. No JPGBoost Free, o limite de um único perfil também se aplica aqui: POST /v1/profiles recusa a criação de um segundo perfil, mas continua aceitando sobrescrever o perfil existente com o mesmo nome.

# Criar ou substituir um perfil (mesmo nome = substituição)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/caminho/de/saida"}' \
  "$BASE/profiles"

# Listar os perfis
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Eliminar um perfil (o espaço transforma-se em %20 no URL)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

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

# Exportar para a pasta do perfil, sem voltar a indicar "folder"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

Verificar que tudo funciona

Dois scripts são incluídos dentro do aplicativo, em Contents/Resources. Execute-os com o JPGBoost aberto e a API ativada. Pedem o token pelo teclado, a menos que a variável de ambiente TOKEN já esteja definida, o que permite encadeá-los numa integração contínua.

Conjunto de verificações

Verifica a autenticação, o encaminhamento e a validação de parâmetros, com uma saída ✓/✗. Apenas leitura por padrão; se lhe for dada uma imagem, também realiza um ciclo real de importação e exportação.

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

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /caminho/para/imagem.png

Percurso guiado

Percorre passo a passo a sequência completa descrita acima de forma legível, desde a recusa sem token até à exportação final, passando pelo estado, pela importação, pelos ajustes e pela lista.

"$SCRIPTS/local_api_demo.sh" /caminho/para/imagem.png

Segurança e privacidade

• O servidor só escuta na interface de loopback (127.0.0.1), o que significa que só é acessível a partir do seu Mac. Nunca está exposto à internet.
• Nenhuma imagem viaja pela internet. A API apenas controla o motor de compressão local.
• O token é gerado na sua máquina. Regenere-o se achar que pode ter sido divulgado, por exemplo após colá-lo num script partilhado.
• Desative a API quando não a estiver a usar: esse é o seu estado padrão.