Transformações de imagem e vídeo

O Proxy de mídia redimensiona e converte imagens, preserva ou remove animações e extrai miniaturas estáticas de vídeos. As rotas de anexos e mídias externas assinadas compartilham o mesmo conjunto de parâmetros, enquanto assets de imagem possuem regras simplificadas próprias.

Quando ocorre uma transformação

Rotas de temas, sons de entrada e objetos estáticos nunca executam transformações.

Requisições de anexos ou mídias externas acionam transformações quando width, height, format ou quality estão presentes, ou quando animated=true.

O Proxy de mídia sempre rasteriza arquivos SVG em anexos quando nenhuma transformação é solicitada (convertendo para WebP sem perdas no modo mp).

Assets de imagem sempre passam pelo motor de transformação, retornando os bytes originais apenas quando o formato e as dimensões já coincidirem com o solicitado.

Parâmetros de representação

Campo	Tipo	Descrição
width?1	integer	Largura de saída desejada (anexos e mídias externas)
height?1	integer	Altura de saída desejada (anexos e mídias externas)
size?2	integer	Dimensão do lado quadrado para assets de imagem
format?3	string	Formato de saída desejado
quality?	string	Perfil de qualidade
animated?4	boolean	Se a saída deve ser animada
effort?	integer	Nível de esforço do encoder WebP (1 a 9)
download?	boolean	Força Content-Disposition: attachment

¹ Inteiros de 1 até 16.384

² Encaixa na escala fixa (ladder): 16, 32, 64, 128, 256, 512, 1024, etc.

³ Aceito também como fmt em assets de imagem

⁴ true ou 1 solicita animação; false ou 0 extrai o primeiro quadro estático

Geometria e redimensionamento

Transformações nunca aumentam o tamanho de uma imagem (não fazem upscale).

• Informar apenas width redimensiona proporcionalmente pela largura.
• Informar apenas height redimensiona proporcionalmente pela altura.
• Informar ambos (width e height) realiza cover crop (recorte central cobrindo a área solicitada).
• Saídas animadas sempre se ajustam dentro dos limites sem recortar (fit).

Formatos para anexos e mídias externas

Valor	Formato de saída	Content-Type
png	PNG	image/png
jpg, jpeg	JPEG	image/jpeg
webp	WebP	image/webp
gif	GIF	image/gif
apng	APNG	image/apng
avif, heic, heif, jxl, svg	WebP (convertido)	image/webp

Qualidade

Valor	Descrição
low	Qualidade 65 com esforço WebP 2
auto	Resolve para lossless ou high
high	Qualidade 85 (padrão para assets)
lossless	WebP sem perdas ou JPEG qualidade 100

Miniaturas de vídeo (Thumbnails)

Para extrair o quadro de miniatura de um vídeo, forneça um format de imagem (ex.: ?format=webp&width=640). O vídeo original nunca é transcodificado.