Documentação da API do Tinify para HTTP

Selecione a linguagem

A API do Tinify permite comprimir e otimizar imagens AVIF, JPEG XL, WebP, JPEG e PNG. Ela foi projetada como um serviço REST. Esta página descreve a API HTTP pura. Também mantemos bibliotecas cliente em várias linguagens que facilitam muito a interação com a API do Tinify.

A API está hospedada em api.tinify.com

Instalação

Para seguir os exemplos abaixo, o curl precisa estar instalado. Verifique com:

curl --version

Se ele não estiver instalado, consulte as instruções oficiais de instalação:

https://curl.se/download.html

Autenticação

Para usar a API, você precisa fornecer sua chave de API. Você pode obter uma chave de API informando seu nome e endereço de e-mail. Mantenha sempre sua chave de API em segredo! Faça suas requisições a partir do seu servidor, e não de uma página da web: a API não aceita requisições de navegadores em outros sites, e a página revelaria sua chave.

A autenticação na API é feita com HTTP Basic Auth. Todas as requisições exigem um cabeçalho Authorization que contenha a string de autenticação api:YOUR_API_KEY codificada em Base64, em que YOUR_API_KEY é a chave que você encontra na página da sua conta da API.

Todas as requisições devem ser feitas por uma conexão HTTPS criptografada, usando TLS 1.2 ou posterior.

Comprimir imagens

Você pode enviar qualquer imagem AVIF, JPEG XL, WebP, JPEG ou PNG para a API do Tinify para comprimi-la. Detectaremos automaticamente o tipo de imagem e a otimizaremos com o mecanismo do TinyPNG ou do TinyJPG, conforme o caso. Você também pode enviar imagens HEIC, que são comprimidas para JPEG. A compressão começará assim que você enviar um arquivo ou fornecer a URL da imagem.

As imagens podem ter até 500 MB e 256 megapixels, e no máximo 150.000 pixels de largura ou de altura. A imagem comprimida fica disponível por 8 horas após o envio, para que você possa baixá-la, redimensioná-la, convertê-la ou armazená-la.

Exemplo de envio a partir de um arquivo

Você pode enviar um arquivo local. Os dados do POST contêm o binário da imagem.

Requisição HTTP

POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

[binary]

Resposta HTTP

HTTP/1.1 201 Created
Compression-Count: 1
Location: https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp
Content-Type: application/json

{
  "input": {
    "size": 207565,
    "type": "image/jpeg"
  },
  "output": {
    "size": 46480,
    "type": "image/jpeg",
    "width": 530,
    "height": 300,
    "ratio": 0.2239,
    "url": "https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp"
  }
}

Por exemplo, se você tiver um arquivo chamado unoptimized.jpg no diretório atual:

curl https://api.tinify.com/shrink \
     --user api:YOUR_API_KEY \
     --data-binary @unoptimized.jpg \
     --dump-header /dev/stdout

Exemplo de envio a partir de uma URL

Você também pode fornecer uma URL da sua imagem em vez de precisar enviá-la. A API aceita um corpo JSON com a URL da imagem como local source.

Requisição HTTP

POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "source": {
    "url": "https://tinypng.com/images/panda-happy.png"
  }
}

Resposta HTTP

HTTP/1.1 201 Created
Compression-Count: 1
Location: https://api.tinify.com/output/cc754aqye6299pggptshe175hdaskg0h
Content-Type: application/json

{
  "input": {
    "size": 75553,
    "type": "image/png"
  },
  "output": {
    "size": 30734,
    "type": "image/png",
    "width": 400,
    "height": 400,
    "ratio": 0.4068,
    "url": "https://api.tinify.com/output/cc754aqye6299pggptshe175hdaskg0h"
  }
}

Por exemplo, se a sua origem for https://tinypng.com/images/panda-happy.png:

curl https://api.tinify.com/shrink \
     --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --data '{"source": {"url": "https://tinypng.com/images/panda-happy.png"} }' \
     --dump-header /dev/stdout

Exemplo de requisição de download

A imagem comprimida pode ser obtida usando a URL do cabeçalho Location da etapa anterior.

Requisição HTTP

GET /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 1
Image-Width: 530
Image-Height: 300
Content-Type: image/jpeg
Content-Length: 46480

[binary]

Por exemplo, você pode salvar a imagem comprimida em um arquivo chamado optimized.jpg e abri-lo:

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
     --user api:YOUR_API_KEY \
     --output optimized.jpg

open optimized.jpg

Redimensionar imagens

Use a API para criar versões redimensionadas das imagens que você enviou. Deixando o redimensionamento a cargo da API, você não precisa escrever esse código e só precisa enviar sua imagem uma vez. As imagens redimensionadas serão comprimidas de forma otimizada, com uma aparência bonita e nítida.

Você também pode aproveitar o recorte inteligente para criar miniaturas que se concentram nas áreas visualmente mais importantes da sua imagem.

O redimensionamento conta como uma compressão adicional. Por exemplo, se você enviar uma única imagem e obtiver a versão otimizada mais 2 versões redimensionadas, isso contará como 3 compressões no total.

Exemplo de requisição de redimensionamento

Você pode redimensionar uma imagem usando a URL retornada no cabeçalho Location após a compressão. É preciso fornecer um corpo de requisição JSON junto com um cabeçalho Content-Type: application/json.

Requisição HTTP

POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "resize": {
    "method": "fit",
    "width": 150,
    "height": 100
  }
}

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 2
Content-Type: image/jpeg
Image-Width: 150
Image-Height: 85
Content-Length: 12594

[binary]

Por exemplo, para salvar a imagem redimensionada e comprimida em um arquivo chamado thumbnail.jpg:

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
     --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --data '{ "resize": { "method": "fit", "width": 150, "height": 100 } }' \
     --dump-header /dev/stdout --silent \
     --output thumbnail.jpg

Opções da requisição

O method descreve a forma como sua imagem será redimensionada. Os seguintes métodos estão disponíveis:

scale

Reduz a imagem proporcionalmente. Você deve fornecer uma largura ou uma altura de destino, mas não ambas. A imagem redimensionada terá exatamente a largura ou a altura fornecida.

fit

Reduz a imagem proporcionalmente para que ela caiba nas dimensões informadas. Você deve fornecer tanto a largura quanto a altura. A imagem redimensionada não excederá nenhuma dessas dimensões.

cover

Redimensiona a imagem proporcionalmente e a recorta, se necessário, para que o resultado tenha exatamente as dimensões informadas. Você deve fornecer tanto a largura quanto a altura. As partes da imagem que são cortadas são determinadas automaticamente. Um algoritmo inteligente determina as áreas mais importantes da sua imagem.

thumb

Uma implementação mais avançada de cover que também detecta imagens de objetos recortados sobre fundos lisos. A imagem é reduzida para a largura e a altura que você fornecer. Se for detectada uma imagem com um objeto isolado, o método adiciona mais espaço de fundo onde for necessário ou recorta as partes sem importância.

Se as dimensões de destino forem maiores que as dimensões originais, a imagem não será ampliada. A ampliação é evitada para proteger a qualidade das suas imagens. Isso significa que cover pode retornar uma imagem menor que as dimensões de destino, enquanto thumb ainda retorna uma imagem de objeto recortado nas dimensões de destino, adicionando fundo ao redor dela.

Converter imagens

Você pode usar a API para converter suas imagens para o tipo de imagem desejado. Atualmente, o Tinify oferece suporte à conversão entre AVIF, JPEG XL, WebP, JPEG e PNG. Quando você informa mais de um tipo de imagem na sua requisição de conversão, a menor versão é retornada para você.

Converter uma imagem conta como uma compressão adicional.

Exemplo de requisição de conversão

Requisição HTTP

POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "convert": { "type": "image/webp" }
}

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 2
Content-Type: image/webp
Image-Width: 530
Image-Height: 300
Content-Length: 46480

[binary]

Por exemplo, para salvar uma imagem PNG ou JPEG comprimida como um arquivo WebP chamado panda-sticker.webp:

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
     --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --data '{ "convert": { "type": "image/webp"} }' \
     --dump-header /dev/stdout \
     --output panda-sticker.webp

Imagens com transparência

Para converter uma imagem com fundo transparente para JPEG, que não oferece suporte a transparência, especifique, com o objeto transform, uma cor de fundo que substitua a transparência. Sem ela, o JPEG é ignorado quando você solicita mais de um tipo de imagem, e uma requisição só de JPEG falha com um erro 400 Bad Request.

Exemplo de requisição de conversão e transformação

Se quiser converter uma imagem com fundo transparente em uma imagem com fundo sólido, especifique uma propriedade background no objeto transform. Se essa propriedade for fornecida, o fundo da imagem transparente será preenchido.

Requisição HTTP

POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "convert" : {
    "type": "image/jpeg"
  },
  "transform": {
    "background": "#000000"
  }
}

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 2
Content-Type: image/jpeg
Image-Width: 530
Image-Height: 300
Content-Length: 46480

[binary]

Por exemplo, se você tiver uma imagem com fundo transparente e quiser salvá-la como JPEG:

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
     --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --data '{ "convert" : {"type": "image/jpeg"}, "transform": {"background": "#000000"}}' \
     --dump-header /dev/stdout \
     --output panda-sticker.jpg

Opções da requisição

Você pode fornecer as seguintes opções para converter sua imagem:

Preservar metadados

Você pode solicitar que metadados específicos sejam copiados da imagem enviada para a versão comprimida. Atualmente, é possível preservar as informações de direitos autorais (copyright), a localização GPS (location) e a data de criação (creation). Preservar metadados aumenta o tamanho do arquivo comprimido, por isso preserve apenas os metadados que for importante manter.

Preservar metadados não conta como uma compressão extra. No entanto, em segundo plano, a imagem será criada novamente com os metadados adicionais.

Exemplo de requisição de envio

Primeiro, você precisa enviar a imagem original, de forma semelhante aos exemplos anteriores.

Requisição HTTP

POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

[binary]

Resposta HTTP

HTTP/1.1 201 Created
Compression-Count: 1
Location: https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp
Content-Type: application/json

{
  "output": {
    "size": 45974,
    "type": "image/jpeg"
  }
}

Por exemplo, se você tiver um arquivo chamado unoptimized.jpg na pasta atual:

curl https://api.tinify.com/shrink \
     --user api:YOUR_API_KEY \
     --data-binary @unoptimized.jpg \
     --dump-header /dev/stdout

Exemplo de requisição de download com metadados

Agora você pode baixar a versão comprimida da imagem com as informações de direitos autorais e a data de criação. Especifique a URL retornada no cabeçalho Location na etapa anterior e adicione as instruções JSON para preservar (preserve) os direitos autorais e a data de criação, da seguinte forma.

Requisição HTTP

POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "preserve": ["copyright", "creation"]
}

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 1
Content-Type: image/jpeg
Image-Width: 530
Image-Height: 300
Content-Length: 46480

[binary]

Observe que o Content-Length será um pouco maior que o size de saída da primeira etapa.

O exemplo a seguir mostra como salvar a imagem comprimida em um arquivo chamado optimized-copyright.jpg, com os metadados de direitos autorais preservados.

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
     --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --data '{ "preserve": ["copyright", "creation"] }' \
     --dump-header /dev/stdout \
     --output optimized-copyright.jpg

Opções da requisição

Você pode fornecer as seguintes opções para preservar metadados específicos. Nenhum metadado será adicionado se os metadados solicitados não estiverem presentes na imagem enviada.

Salvar no Amazon S3

Você pode pedir à API do Tinify que salve as imagens comprimidas diretamente no seu Amazon S3. Esse recurso é útil se você usa o S3 para hospedar imagens, pois elimina a necessidade de baixá-las para o seu servidor e enviá-las manualmente para o S3. Uma requisição que armazena uma imagem conta como uma compressão adicional, mesmo quando também redimensiona ou converte a imagem.

Exemplo de requisição ao S3

Você pode armazenar uma imagem comprimida no S3 usando a URL retornada no cabeçalho Location. A requisição que instrui o armazenamento do arquivo no S3 deve incluir um corpo JSON com as informações do bucket e um cabeçalho Content-Type: application/json.

Requisição HTTP

POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "store" : {
    "service": "s3",
    "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-west-1",
    "path": "example-bucket/my-images/optimized.jpg"
  }
}

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 2
Image-Width: 530
Image-Height: 300
Location: https://s3.us-west-1.amazonaws.com/example-bucket/my-images/optimized.jpg
Content-Type: application/json

{
  "status": "success"
}

Por exemplo, para salvar a imagem comprimida em um arquivo chamado my-images/optimized.jpg em um bucket chamado example-bucket:

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
     --user api:YOUR_API_KEY \
     --dump-header /dev/stdout --silent \
     --header "Content-Type: application/json" \
     --data '{
       "store" : {
         "service": "s3",
         "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
         "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
         "region": "us-west-1",
         "headers": {
           "Cache-Control": "public, max-age=31536000"
         },
         "path": "example-bucket/my-images/optimized.jpg"
       }
     }'

Opções da requisição

Você precisa fornecer as seguintes opções para salvar uma imagem no Amazon S3:

As seguintes configurações são opcionais:

Exemplo de política de acesso ao S3

Se quiser criar um usuário com acesso limitado especificamente para a API do Tinify, você pode usar o seguinte exemplo de política como ponto de partida:

{
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:PutObject",
      "s3:PutObjectAcl"
    ],
    "Resource": [
      "arn:aws:s3:::example-bucket/*"
    ]
  }
}

Salvar no Google Cloud Storage

Você pode instruir a API do Tinify a salvar as imagens comprimidas diretamente no Google Cloud Storage. Se você usa o GCS para hospedar suas imagens, isso evita o trabalho de baixar as imagens para o seu servidor e enviá-las você mesmo para o GCS. Uma requisição que armazena uma imagem conta como uma compressão adicional, mesmo quando também redimensiona ou converte a imagem.

Antes de poder armazenar uma imagem no GCS, você precisará gerar um token de acesso com uma conta de serviço.

As imagens são armazenadas com leitura pública, com a ACL predefinida publicRead. Isso não funciona em buckets com acesso uniforme no nível do bucket, que não oferecem suporte a ACLs, nem em buckets com prevenção do acesso público, que rejeitam ACLs públicas. Uma política da organização pode impor qualquer uma dessas configurações.

Exemplo de requisição ao GCS

Você pode armazenar uma imagem comprimida no GCS usando a URL retornada no cabeçalho Location. A requisição que instrui o armazenamento do arquivo no GCS deve incluir um corpo JSON com as informações do bucket e um cabeçalho Content-Type: application/json.

Requisição HTTP

POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json

{
  "store" : {
    "service": "gcs",
    "gcp_access_token": "YOUR_GCP_TOKEN_HERE",
    "path": "example-bucket/my-images/optimized.jpg"
  }
}

Resposta HTTP

HTTP/1.1 200 OK
Compression-Count: 2
Image-Width: 530
Image-Height: 300
Location: https://storage.googleapis.com/example-bucket/my-images/optimized.jpg
Content-Type: application/json

{
  "status": "success"
}

Por exemplo, para salvar a imagem comprimida em um arquivo chamado my-images/optimized.jpg em um bucket chamado example-bucket:

curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
    --user api:YOUR_API_KEY \
    --dump-header /dev/stdout --silent \
    --header "Content-Type: application/json" \
    --data '{
      "store" : {
        "service": "gcs",
        "gcp_access_token": "EXAMPLE_TOKEN_Ag_0HvsglgriGU_EXAMPLE_TOKEN",
        "headers": {
          "Cache-Control": "public, max-age=31536000"
        },
        "path": "example-bucket/my-images/optimized.jpg"
      }
    }'

Opções da requisição

Você precisa fornecer as seguintes opções para salvar uma imagem no Google Cloud Storage:

As seguintes configurações são opcionais:

Salvar em armazenamento compatível com S3

Embora a API do Tinify não ofereça uma solução integrada para salvar as imagens diretamente em provedores de armazenamento compatíveis com S3 além da Amazon, você ainda pode salvar suas imagens usando o exemplo da linguagem de programação escolhida.

A API do S3 é usada por provedores de armazenamento como DigitalOcean Spaces, Backblaze, G-Core Storage, Wasabi, CenturyLink Object Storage, Filebase e muitos outros.

Escolha uma linguagem no topo da página para ver o código de exemplo.

A documentação detalhada sobre como usar a API do S3 pode ser encontrada aqui.

Salvar no Microsoft Azure

Embora a API do Tinify não ofereça uma solução integrada para salvar as imagens diretamente no armazenamento do Microsoft Azure, você ainda pode salvar suas imagens usando o exemplo da linguagem de programação escolhida.

Escolha uma linguagem no topo da página para ver o código de exemplo.

A documentação detalhada sobre como usar a API de armazenamento do Azure pode ser encontrada aqui.

Tratamento de erros

A API do Tinify usa códigos de status HTTP para indicar sucesso ou falha. Códigos de status na faixa 2xx indicam sucesso. Códigos de status na faixa 4xx indicam que houve um problema com a sua requisição. Códigos de status na faixa 5xx indicam um problema temporário com a API do Tinify.

Os erros mais comuns são:

• 400 Bad Request: a requisição é inválida, por exemplo, por causa de uma opção desconhecida ou porque a imagem não pode ser decodificada ou excede os limites. Altere a requisição antes de tentar novamente.
• 401 Unauthorized: a chave de API está ausente ou é inválida.
• 404 Not Found: a URL de saída não existe ou expirou. As URLs de saída ficam disponíveis por 8 horas após o envio da imagem.
• 415 Unsupported Media Type: o arquivo não é de um tipo de imagem compatível com a API.
• 429 Too Many Requests: seu limite mensal de compressões foi atingido ou você está fazendo requisições rápido demais. O campo message informa qual dos dois. No primeiro caso, aguarde até o próximo mês do calendário ou faça upgrade da sua assinatura; no segundo, adicione um intervalo entre requisições consecutivas. A resposta não tem o cabeçalho Retry-After.
• 5xx: um problema temporário com a API do Tinify. É seguro tentar a requisição novamente após alguns minutos.

Exemplo de resposta de erro

Caso ocorra um erro, o corpo HTTP conterá os detalhes do erro formatados em JSON. O campo message conterá uma breve descrição legível por humanos.

Requisição HTTP

POST /shrink HTTP/1.1
Host: api.tinify.com

Resposta HTTP

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Unauthorized",
  "message": "Credentials are invalid."
}

Contagem de compressões

O serviço web registra o número de compressões que você fez. A maioria das respostas HTTP inclui o número de compressões feitas neste mês.

Exemplo de resposta

Na maioria das respostas está presente o cabeçalho Compression-Count, que contém o número de compressões feitas com esta chave de API durante o mês do calendário atual (UTC).

Requisição HTTP

POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

[binary]

Resposta HTTP

HTTP/1.1 201 Created
Compression-Count: 12

[...]

Cada envio conta como uma compressão, a menos que o arquivo não possa ficar menor. Enviar a mesma imagem novamente com a mesma chave de API não conta durante as 8 horas seguintes ao envio que foi contado. Uma requisição que redimensiona, converte ou armazena a imagem comprimida conta como mais uma, mesmo quando faz várias dessas operações ao mesmo tempo. Baixar a imagem comprimida e preservar metadados não contam. Seu limite mensal se aplica a todas as chaves de API da sua conta em conjunto; por isso, com mais de uma chave, a contagem de cada chave pode ser menor que o total da sua conta.

Obtenha sua chave de API

Você pode obter sua chave de API em https://tinypng.com/developers

Precisa de ajuda? Tem algum feedback?

Estamos sempre aqui para ajudar: se você estiver com alguma dificuldade, é só escrever para support@tinify.com. Também é o lugar perfeito para nos enviar todas as suas sugestões e comentários.