Ir para o conteúdo

Transformação de Imagens

Aplique transformações em tempo real em imagens sem precisar re-fazer upload. Todos os comandos de transformação usam a sintaxe do ImageMagick — a ferramenta padrão da indústria para processamento de imagens.

Como funciona

Passe comandos do ImageMagick através do parâmetro de consulta format. O GFile executa a transformação, armazena em cache o resultado como sub-arquivo e retorna a imagem processada. Use $INPUT e $OUTPUT.<ext> como marcadores para os arquivos de origem e destino.

/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=<comando-imagemagick>&apiKey=<your-api-key>

Transformações disponíveis

Operação Comando Descrição
Redimensionar -resize 300x200 Redimensionar para largura×altura
Rotacionar -rotate 90 Rotacionar por ângulo (graus)
Inverter vertical -flip Inverter verticalmente
Inverter horizontal -flop Inverter horizontalmente
Escala de cinza -colorspace Gray Converter para escala de cinza
Desfoque -blur 0x5 Aplicar desfoque gaussiano (raio×sigma)
Nitidez -sharpen 0x1 Aumentar nitidez
Conversão de formato -format webp Converter para outro formato
Qualidade -quality 80 Definir qualidade de compressão (1-100)
Recorte -crop 200x200+50+50 Recortar para largura×altura em deslocamento +x+y
Miniatura -thumbnail 150x150^ Criar miniatura com preenchimento proporcional
Remover metadados -strip Remover EXIF e metadados

Exemplos

Redimensionar uma imagem

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=-resize 200x200&apiKey=<your-api-key>"
  • -resize 200x200 redimensiona para caber dentro de 200×200 pixels, preservando a proporção

Converter formato e definir qualidade

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=$INPUT -quality 80 $OUTPUT.webp&apiKey=<your-api-key>"
  • $INPUT referencia o arquivo original
  • -quality 80 define a qualidade de compressão em 80%
  • $OUTPUT.webp gera saída no formato WebP

Criar uma miniatura centralizada

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=$INPUT -resize 150x150^ -gravity center -extent 150x150 $OUTPUT.png&apiKey=<your-api-key>"
  • -resize 150x150^ redimensiona para preencher a área de 150×150 (pode transbordar)
  • -gravity center ancora o recorte no centro
  • -extent 150x150 recorta exatamente para 150×150 pixels

Compor imagens (sobreposição de marca d'água)

Referencie outros arquivos no seu pipeline de transformação usando $<file-uuid>:

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=$INPUT $<watermark-file-uuid>.png -gravity southeast -composite $OUTPUT.png&apiKey=<your-api-key>"
  • $<watermark-file-uuid>.png referencia outro arquivo armazenado no GFile
  • -gravity southeast posiciona a sobreposição no canto inferior direito
  • -composite mescla as imagens

Obter metadados de imagem

Recupere informações técnicas detalhadas (dimensões, formato, espaço de cor):

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/info?apiKey=<your-api-key>"

Retorna a saída JSON do ImageMagick com dimensões, formato, espaço de cor e mais.