# Parâmetros de URL do Image Processor A query string `ims` carrega a transformação que [Image Processor](/pt-br/documentacao/plataforma/applications/#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: ![A fotografia de origem redimensionada para um quadrado de 400 por 400 pixels, centralizada e recortada automaticamente a partir do original em formato paisagem](/assets/docs/images/image-processor/Image_Processor_1.png?ims=400x400) --- ## 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: ![A fotografia de origem recortada para o retângulo entre as coordenadas 430x20 e 910x730 pixels](/assets/docs/images/image-processor/Image_Processor_1.png?ims=430x20:910x730) --- ## 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. > **Atenção** > > Uma imagem com proporção de 1:1 mantém as suas dimensões. Uma imagem não quadrada girada em `90` ou `270` tem os valores de altura e largura trocados. A imagem abaixo carrega `?ims=filters:rotate(270)`: ![A fotografia de origem girada 270 graus para a esquerda, de modo que o original em formato paisagem é renderizado como uma imagem retrato](/assets/docs/images/image-processor/Image_Processor_1.png?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. > **nota** > > Uma requisição para uma resolução maior que a original não amplia a imagem. A imagem é exibida na maior resolução possível. A imagem abaixo carrega `?ims=filters:quality(15)`, bem abaixo do valor recomendado: ![A fotografia de origem entregue com um valor de qualidade de 15](/assets/docs/images/image-processor/Image_Processor_1.png?ims=filters:quality\(15\)) --- ## 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: ![O logotipo da Azion posicionado sobre a fotografia de origem, centralizado nos dois eixos com 50% de transparência](/assets/docs/images/image-processor/Image_Processor_1.png?ims=filters:watermark\(https://www.azion.com/assets/docs/images/azion-logo.png,center,center,50\)) --- ## 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](/pt-br/documentacao/guias/performance-e-confiabilidade/otimizacao-de-entrega/processar-imagens/). A imagem abaixo carrega `?ims=filters:format(gif)`: ![A fotografia de origem em PNG convertida para o formato GIF](/assets/docs/images/image-processor/Image_Processor_1.png?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)`: ![A fotografia de origem ajustada a uma área de 400 por 400 pixels, com cinza preenchendo o espaço acima e abaixo dela](/assets/docs/images/image-processor/Image_Processor_1.png?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: ![A fotografia de origem ajustada a uma área de 400 por 400 pixels, com a cor 00ffff preenchendo o espaço acima e abaixo dela, em qualidade 100](/assets/docs/images/image-processor/Image_Processor_1.png?ims=fit-in/400x400/filters:fill\(00ffff\):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](https://caniuse.com/webp) e [Suporte de navegadores para AVIF](https://caniuse.com/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](/pt-br/documentacao/plataforma/applications/image-processor/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`. | --- ## Recursos relacionados - [Entrega de imagens](/pt-br/documentacao/plataforma/applications/image-processor/entrega-de-imagens.md): O caminho que uma requisição percorre pelo módulo, e como uma imagem derivada é armazenada em cache. - [Configurações do Image Processor](/pt-br/documentacao/plataforma/applications/image-processor/configuracoes.md): Os campos e as interfaces que ativam o módulo para uma aplicação. - [Limites](/pt-br/documentacao/plataforma/applications/limites.md#image-processor): Os tetos de tamanho e dimensão que limitam os valores nestas tabelas. - [Configurar Image Processor](/pt-br/documentacao/guias/performance-e-confiabilidade/otimizacao-de-entrega/processar-imagens.md): Ative o módulo, adicione as regras que processam imagens e configure o cache.