CDN de imagens

Quando você consulta conteúdo, os campos de arquivo devolvem URLs do CDN que podem ser usadas direto nos aplicativos. Em imagens, você pode acrescentar parâmetros de consulta para redimensionar, recortar, converter o formato e ajustar a qualidade na hora, sem um pipeline de imagens separado.

A entrega pelo CDN é pública: solicitações GET não precisam de uma chave de API. Em aplicativos TypeScript, use buildCdnUrl de @contismo/sdk para montar URLs de transformação com opções tipadas.

URLs dos recursos

Os campos de arquivo expõem:

url: o recurso completo no CDN
thumbnailUrl: uma prévia menor gerada no envio (quando disponível)

Use esses valores do GraphQL ou da API REST de recursos como estão. Os caminhos incluem o projeto e o ambiente, então sempre busque o conteúdo do ambiente que você pretende entregar.

Forma típica do caminho:

/{projectId}/{environmentId}/{assetId}.{ext}

Transformações de imagem

Acrescente parâmetros de consulta à url de uma imagem para pedir uma variante transformada. Os parâmetros correspondem às opções de código aberto (não Pro) do imgproxy.

Valores compostos usam dois-pontos, na mesma ordem de argumentos do imgproxy. Por exemplo, g=fp:0.5:0.3 ou pad=10:20:10:20.

Tamanho e redimensionamento

Parâmetro	Alias	Valores	Padrão	Finalidade
`w`		inteiro positivo	nenhum	Largura em pixels
`h`		inteiro positivo	nenhum	Altura em pixels
`fit`		`fit`, `fill`, `fill-down`, `force`, `auto` ou `crop`	`fit`	Modo de redimensionamento (`crop` é um alias de `fill`)
`mw`		inteiro positivo	nenhum	Largura mínima
`mh`		inteiro positivo	nenhum	Altura mínima
`z`	`zoom`	número, ou `x:y`	`1`	Fatores de zoom
`dpr`		número positivo	`1`	Proporção de pixels do dispositivo
`el`	`enlarge`	`1`, `t` ou `true`	desativado	Permitir ampliar origens menores
`ex`	`extend`	`1` ou `1:gravity...`	desativado	Estender a tela até o tamanho de destino
`exar`	`extend_ar`	`1` ou `1:gravity...`	desativado	Estender até a proporção solicitada

Modos de fit:

fit: dimensionar para caber dentro de w × h, mantendo a proporção
fill / crop: preencher w × h e recortar o excesso
fill-down: como fill, mas recorta para baixo se o resultado for menor do que o solicitado
force: esticar até w × h exatos
auto: fill quando a orientação coincide; caso contrário, fit

Recorte, gravidade e aparo

Parâmetro	Alias	Valores	Finalidade
`g`	`gravity`	veja abaixo	Ponto focal ao recortar ou estender
`c`	`crop`	`width:height[:gravity...]`	Recortar antes de redimensionar (tamanhos absolutos ou relativos)
`trim`		`threshold[:color[:equal_hor[:equal_ver]]]`	Remover o fundo ao redor

Tipos de gravidade (g):

Bordas e cantos: no, so, ea, we, noea, nowe, soea, sowe, ce
Deslocamentos opcionais: ce:10:20 (absoluto se for 1 ou maior, relativo se estiver entre 0 e 1)
Inteligente: sm
Ponto de foco: fp:0.5:0.3 (x/y de 0 a 1)

Preenchimento, rotação e inversão

Parâmetro	Alias	Valores	Finalidade
`pad`	`padding`	`top[:right[:bottom[:left]]]`	Preenchimento no estilo CSS depois das transformações
`autorotate`		`1` / `true` ou `0` / `false`	Respeitar a orientação EXIF
`rot`	`rotate`	`0`, `90`, `180`, `270`, …	Girar em ângulos retos
`flip`		`horizontal[:vertical]` (`1`/`true`)	Inverter eixos
`bg`	`background`	hexadecimal (`fff`, `ffffff`) ou `R:G:B`	Preenchimento de fundo (útil para JPEG a partir de origens transparentes)

Efeitos

Parâmetro	Alias	Valores	Finalidade
`bl`	`blur`	número positivo (sigma)	Desfoque gaussiano
`sh`	`sharpen`	número positivo (sigma)	Nitidez
`pix`	`pixelate`	inteiro positivo	Tamanho do bloco de pixelização

Qualidade e formato de saída

Parâmetro	Alias	Valores	Padrão	Finalidade
`q`		inteiro 0–100	`75`	Qualidade de saída
`fq`		pares `format:quality:...`		Qualidade por formato, por exemplo `jpeg:80:webp:70`
`fmt`		`webp`, `avif`, `jpg`, `jpeg`, `png`, `gif`, `ico`, `heic`, `bmp`, `tiff`	origem	Formato de saída (`jpeg` → `jpg`)
`mb`	`max_bytes`	inteiro positivo	nenhum	Reduzir a qualidade até ficar abaixo deste tamanho em bytes (`jpg`, `webp`, `heic`, `tiff`)

Metadados e cor

Parâmetro	Alias	Valores	Finalidade
`sm`	`strip_meta`	`1`/`true` ou `0`/`false`	Remover metadados EXIF/IPTC
`kcr`	`keep_copyright`	`1`/`true`	Manter o copyright ao remover metadados
`scp`	`strip_icc`	`1`/`true` ou `0`/`false`	Converter ICC para sRGB e remover o perfil
`ph`	`preserve_hdr`	`1`/`true` ou `0`/`false`	Manter a profundidade de bits alta
`eth`	`enforce_thumb`	`1`/`true`	Preferir a miniatura HEIC/AVIF incorporada quando existir

Ajudas de entrega

Parâmetro	Alias	Valores	Finalidade
`raw`		`1` / `true`	Transmitir o arquivo de origem sem processamento
`fn`	`filename`	nome do arquivo	Nome de arquivo de `Content-Disposition`
`att`	`attachment`	`1` / `true`	Forçar o download (`attachment`)

Exemplos

<img src="https://cdn.contismo.com/.../photo.jpg?w=800&fmt=webp" alt="" />

<img
  src="https://cdn.contismo.com/.../photo.jpg?w=400&h=400&fit=fill&g=fp:0.5:0.35&q=80&dpr=2"
  alt=""
/>

<img
  src="https://cdn.contismo.com/.../photo.jpg?w=1200&fmt=avif&q=70&bl=0.5"
  alt=""
/>

<img
  src="https://cdn.contismo.com/.../logo.png?w=200&bg=ffffff&fmt=jpg"
  alt=""
/>

<!-- Recortar e depois redimensionar; remover metadados -->
<img
  src="https://cdn.contismo.com/.../photo.jpg?c=0.8:0.8:ce&w=800&fit=fill&sm=1"
  alt=""
/>

Você pode combinar os parâmetros livremente. Omita os que não precisar.

Miniaturas

Para listas, cartões e outras prévias pequenas, prefira thumbnailUrl quando estiver presente. As miniaturas são geradas no envio (até 640×640) e evitam uma solicitação de transformação extra para os tamanhos comuns da interface.

Use a url completa com parâmetros de transformação quando precisar de um tamanho, recorte ou formato específico para a imagem principal.

Cache

As respostas transformadas são armazenadas em cache de forma agressiva (Cache-Control: public, max-age=31536000, immutable). A mesma URL de recurso e a mesma query string sempre resolvem para a mesma variante, o que mantém a entrega rápida em canais e dispositivos diferentes.

Limites de largura de banda

Cada plano inclui uma cota mensal de largura de banda do CDN. Se um projeto ultrapassar o limite, o CDN responde com HTTP 429.

Confira o uso atual e os limites do plano no Studio. Reduza o tráfego de saída servindo transformações no tamanho adequado (e miniaturas para prévias) em vez dos originais em resolução completa em todo lugar.