Parâmetros de URL do Image Processor
Consulte a query string ims: redimensionamento, recorte, rotação, qualidade, marca d'água, conversão de formato e preenchimento, com os valores aceitos.
A query string ims carrega a transformação que Image Processor aplica a uma imagem. Uma única string pode conter um redimensionamento, um recorte e uma cadeia de filtros. A plataforma retorna uma imagem derivada, construída a partir da imagem de origem hospedada no servidor de origem, e o original nunca é modificado. Esta página traz a sintaxe de cada operação, os valores que os seus argumentos aceitam e um resultado renderizado.
Redimensionamento
Um redimensionamento define o tamanho da imagem derivada. O tamanho vai na query string como ?ims=WidthxHeight, em pixels, e qualquer uma das dimensões pode ser omitida.
| Argumento | Tipo | Obrigatório | Padrão | O que faz |
|---|---|---|---|---|
Width | Número inteiro de pixels, ou orig | Não | Calculado a partir de Height, com a proporção preservada | Define a largura da imagem derivada. orig mantém a largura original. |
Height | Número inteiro de pixels, ou orig | Não | Calculado a partir de Width, com a proporção preservada | Define a altura da imagem derivada. orig mantém a altura original. |
Os argumentos se combinam em cinco formas:
| Forma | Resultado |
|---|---|
?ims=WidthxHeight | Redimensiona a imagem para esse tamanho. A imagem pode ser recortada automaticamente para se ajustar. |
?ims=Widthx | Define a largura e calcula a altura, com a proporção preservada. |
?ims=xHeight | Define a altura e calcula a largura, com a proporção preservada. |
?ims=WidthxOrig | Define a largura e mantém a altura original, sem recorte automático. |
?ims=fit-in/WidthxHeight | Ajusta a imagem dentro da área, com a proporção preservada e sem ampliação. |
Quando Width e Height são definidos, a imagem pode ser recortada automaticamente para se ajustar ao tamanho solicitado. O recorte é centralizado, e ocorre na vertical ou na horizontal, dependendo de como as dimensões originais se ajustam às solicitadas.
fit-in nunca amplia a imagem: quando a área é maior que as dimensões da imagem, a imagem mantém o tamanho original. As duas dimensões são opcionais, e a imagem cresce até atingir a largura ou a altura, o que vier primeiro. Por exemplo, ?ims=fit-in/400x400 em uma imagem paisagem para em 400 pixels de largura, e a altura fica abaixo de 400.
A imagem abaixo carrega ?ims=400x400, que redimensiona com recorte automático:
Recorte
Um recorte mantém o retângulo entre duas coordenadas da imagem de origem e descarta o restante. As coordenadas vão na query string como ?ims=AxB:CxD, em pixels.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
AxB | Par de coordenadas em pixels | Sim | O canto superior esquerdo onde o recorte começa. |
CxD | Par de coordenadas em pixels | Sim | O canto inferior direito onde o recorte termina. |
Por exemplo, ?ims=430x20:910x730 inicia o recorte na coordenada 430x20 pixels e o termina na coordenada 910x730 pixels.
A imagem abaixo carrega essa query:
Rotação
A rotação gira a imagem para a esquerda por um número fixo de graus. O ângulo vai na query string como ?ims=filters:rotate(Angle).
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
Angle | Um dos valores 0, 90, 180, 270, 360 | Sim | O número de graus que a imagem gira para a esquerda. |
| Valor | Resultado |
|---|---|
0 | Sem rotação. |
90 | Gira a imagem 90 graus para a esquerda. |
180 | Gira a imagem 180 graus para a esquerda. |
270 | Gira a imagem 270 graus para a esquerda. |
360 | Sem rotação. |
Um valor que não está nesta lista não gira a imagem.
A imagem abaixo carrega ?ims=filters:rotate(270):
)
Qualidade
O filtro de qualidade define o quanto a imagem derivada é comprimida, o que altera o tamanho do arquivo e o tempo de transferência. O valor vai na query string como ?ims=filters:quality(value).
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
value | Número inteiro, de 0 a 100 | Sim | O nível de qualidade aplicado à imagem. |
O valor recomendado é 85. Ele otimiza a imagem sem perda perceptível de qualidade visual.
A imagem abaixo carrega ?ims=filters:quality(15), bem abaixo do valor recomendado:
)
Marca d’água
Uma marca d’água posiciona uma segunda imagem sobre a imagem de origem. O filtro vai na query string como ?ims=filters:watermark(WatermarkURL,X,Y,Alpha) e recebe quatro argumentos, nessa ordem.
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
WatermarkURL | URL de uma imagem | Sim | A imagem posicionada sobre a imagem de origem. Parênteses na URL são codificados como %28 para ( e %29 para ). |
X | Número inteiro de pixels, center, ou repeat | Sim | A posição horizontal. Um número positivo desloca a partir da borda esquerda em direção à direita, e um número negativo a partir da borda direita em direção à esquerda. center centraliza a marca d’água horizontalmente, e repeat preenche a imagem horizontalmente com cópias dela. |
Y | Número inteiro de pixels, center, ou repeat | Sim | A posição vertical. Um número positivo desloca de cima para baixo, e um número negativo de baixo para cima. center centraliza a marca d’água verticalmente, e repeat preenche a imagem verticalmente com cópias dela. |
Alpha | Número inteiro, de 0 a 100 | Sim | A transparência da marca d’água. 0 é completamente opaco e 100 é completamente transparente. |
Por exemplo, ?ims=filters:watermark(https://example.com/watermark-image.png,-25,-10,50) aplica a marca d’água 25 pixels à esquerda do centro e 10 pixels abaixo do centro, com 50% de transparência.
A imagem abaixo carrega uma marca d’água centralizada nos dois eixos, com 50% de transparência:
){kind=logo}
Conversão de formato
A conversão de formato retorna a imagem em um formato de arquivo diferente. O formato de destino vai na query string como ?ims=filters:format(ImageFormat).
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
ImageFormat | Um dos valores webp, avif, jpeg, gif, png | Sim | O formato de arquivo da imagem derivada. |
Converter para WEBP ou AVIF exige que a requisição carregue um header Accept que nomeie o formato:
| Formato de saída | Header que a requisição deve carregar |
|---|---|
webp | Accept: image/webp |
avif | Accept: image/avif |
Para adicionar esse header com uma regra, consulte Configurar Image Processor.
A imagem abaixo carrega ?ims=filters:format(gif):
)
Preenchimento
O preenchimento cria uma imagem derivada maior que a original e pinta a área ao redor dela com uma cor. O filtro vai na query string como ?ims=fit-in/WidthxHeight/filters:fill(Color).
| Argumento | Tipo | Obrigatório | O que faz |
|---|---|---|---|
Width | Número inteiro de pixels | Não | A largura da área em que a imagem se ajusta. Se você omiti-la, a largura é calculada a partir de Height, preservando a proporção. |
Height | Número inteiro de pixels | Não | A altura da área em que a imagem se ajusta. Se você omiti-la, a altura é calculada a partir de Width, preservando a proporção. |
Color | Valor de cor hexadecimal, ou o valor nomeado gray | Sim | A cor pintada ao redor da imagem. |
O preenchimento usa o mesmo comportamento de fit-in que um redimensionamento: a imagem mantém a proporção, e uma área maior que a imagem não a amplia. O espaço que sobra é o que a cor preenche.
Por exemplo, ?ims=fit-in/300x400/filters:fill(008080) ajusta a imagem a uma área de 300 por 400 pixels e pinta o espaço ao redor dela com a cor 008080.
A imagem abaixo carrega ?ims=fit-in/400x400/filters:fill(gray):
)
Filtros combinados
Uma única string ims pode carregar mais de um filtro. Os filtros ficam dentro de um único grupo filters:, e um : separa cada um do próximo, como em filters:filter1(arg1):filter2(arg2).
| Segmento | Exemplo | O que faz |
|---|---|---|
| Segmento de redimensionamento | fit-in/400x400 | Define o tamanho da imagem derivada. Vem primeiro, e uma / o separa do grupo de filtros. |
| Grupo de filtros | filters:fill(00ffff):quality(100) | Carrega um ou mais filtros, aberto por filters:. |
| Separador de filtro | : | Separa um filtro do próximo dentro do grupo. |
Por exemplo, ?ims=fit-in/400x400/filters:fill(00ffff):quality(100) ajusta a imagem a uma área de 400 por 400 pixels. Em seguida, pinta o espaço ao redor da imagem com a cor 00ffff e aplica um valor de qualidade de 100.
A imagem abaixo carrega essa query:
:quality(100))
Formatos de entrada compatíveis
Image Processor aceita estes formatos de imagem de origem:
- JPEG
- GIF
- PNG
- BMP
- ICO
- WEBP
- AVIF
WEBP e AVIF dependem do navegador. Para os navegadores que suportam cada um, consulte Suporte de navegadores para WEBP e Suporte de navegadores para AVIF.
Image Processor também converte um formato sem o parâmetro ims na requisição. Ele detecta se o navegador suporta WEBP e converte a imagem quando possível, e imagens BMP são convertidas para JPEG ou WEBP dependendo do mesmo suporte de navegador. Para mais informações, consulte Entrega de imagens.
Posição do parâmetro ims
O parâmetro de query string ims= deve ser o último parâmetro na URL. Quando outro parâmetro de query string vem depois de ims=, a requisição pode retornar um erro 504.
| URL | Posição de ims= |
|---|---|
example.com/image.jpeg?ts=1234&ims=1000x1000 | Último. A requisição é válida. |
example.com/image.jpeg?ims=1000x1000&ts=1234 | Não é o último. A requisição pode retornar um erro 504. |