Documentação da API do Tinify para Java

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. As bibliotecas cliente em várias linguagens facilitam muito a interação com a API do Tinify.

Instalação

Você pode usar o cliente Java como uma dependência do Maven adicionando o seguinte ao pom.xml da sua aplicação. Para evitar alterações incompatíveis no seu código quando atualizarmos o cliente, substitua RELEASE por uma versão específica:

<dependency>
  <groupId>com.tinify</groupId>
  <artifactId>tinify</artifactId>
  <version>RELEASE</version>
</dependency>

Se, em vez disso, você usa o Gradle, pode usar o seguinte:

dependencies {
    compile 'com.tinify:tinify:latest.release'
}

O código-fonte está disponível no GitHub.

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.

import com.tinify.*;

public class Example {
  public static void main(String[] args) {
    Tinify.setKey("YOUR_API_KEY");
  }
}

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

Você pode configurar o cliente da API para fazer todas as requisições por meio de um proxy HTTP. Defina a URL do seu servidor proxy, que pode, opcionalmente, incluir credenciais.

Tinify.setProxy("http://user:pass@192.168.0.1:8080");

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.

Você pode escolher um arquivo local como origem e gravá-lo em outro arquivo.

Source source = Tinify.fromFile("unoptimized.webp");
source.toFile("optimized.webp");

Você também pode enviar uma imagem a partir de um buffer (uma string com dados binários) e obter os dados da imagem comprimida.

byte[] sourceData = Files.readAllBytes(Paths.get("unoptimized.jpg"));
byte[] resultData = Tinify.fromBuffer(sourceData).toBuffer();

Você pode fornecer uma URL da sua imagem em vez de precisar enviá-la.

Source source = Tinify.fromUrl("https://tinypng.com/images/panda-happy.png");
source.toFile("optimized.png");

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.

Para redimensionar uma imagem, chame o método resize em uma origem de imagem:

Source source = Tinify.fromFile("large.jpg");
Options options = new Options()
    .with("method", "fit")
    .with("width", 150)
    .with("height", 100);
Source resized = source.resize(options);
resized.toFile("thumbnail.jpg");

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.

Source source = Tinify.fromFile("panda-sticker.jpg");
Result converted = source.convert(new Options().with("type",new String[]{"image/png","image/webp"} )).result();
String extension = converted.extension();
converted.toFile("panda-sticker." + extension);

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.

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.

Source source = Tinify.fromFile("panda-sticker.png");
Source converted = source.convert(new Options().with("type", "image/jpeg")).transform(new Options().with("background", "#000000"));
converted.toFile("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.

Para preservar metadados específicos, chame o método preserve em uma origem de imagem:

Source source = Tinify.fromFile("large.jpg");
Source copyrighted = source.preserve("copyright", "creation");
copyrighted.toFile("optimized-copyright.jpg");

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.

Para salvar uma imagem no S3, chame o método store em uma origem de imagem:

Source source = Tinify.fromFile("large.jpg");
Options options = new Options()
    .with("service", "s3")
    .with("aws_access_key_id", "AKIAIOSFODNN7EXAMPLE")
    .with("aws_secret_access_key", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
    .with("region", "us-west-1")
    .with("path", "example-bucket/my-images/optimized.jpg");
source.store(options);

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.

Depois de gerar o token de acesso, você pode salvar a imagem otimizada diretamente no GCS chamando o método store em uma origem de imagem:

Source source = Tinify.fromFile("large.jpg");
Options options = new Options()
    .with("service", "gcs")
    .with("gcp_access_token", "EXAMPLE_TOKEN_Ag_0HvsglgriGhoGU_EXAMPLE_TOKEN")
    .with("path", "example-bucket/my-images/optimized.jpg");
source.store(options);

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.

Se você ainda não tem o AWS SDK instalado, pode adicioná-lo com o seguinte comando:

/* You can add the following code to your application’s pom.xml 
 * and replace RELEASE_VERSION with a specific version
 */
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk</artifactId>
    <version>RELEASE_VERSION</version>
</dependency>

Exemplo de armazenamento

Source source = Tinify.fromUrl("https://tinypng.com/images/panda-happy.png");
byte[] resultData = source.toBuffer();


AWSCredentials credentials = new BasicAWSCredentials(
  "KEY_EXAMPLE", 
  "YOUR_SECRET_KEY"
);

AmazonS3 s3client = AmazonS3ClientBuilder
  .standard()
  .withCredentials(new AWSStaticCredentialsProvider(credentials))
  .withEndpointConfiguration(
    new AwsClientBuilder.EndpointConfiguration("https://YOUR-ENDPOINT.com", "REGION"))
  .build();

ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("image/png");
metadata.setContentLength(resultData.length);

s3client.putObject(
  "bucket-name",
  "file-name.png",
  new ByteArrayInputStream(resultData),
  metadata
);

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.

Lembre-se de que você precisará instalar o pacote do Azure Storage com o seguinte comando:

/* You can add the following code to your application’s pom.xml 
 * and replace RELEASE_VERSION with a specific version
 */
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>RELEASE_VERSION</version>
</dependency>

Exemplo de armazenamento

O exemplo a seguir explica como se conectar ao seu contêiner de blobs e enviar sua imagem usando a cadeia de conexão do seu armazenamento do Azure. A cadeia de conexão pode ser encontrada no painel do seu armazenamento do Azure.

String connectStr = "<YOUR_AZURE_STORAGE_CONNECTION_STRING>";

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder().connectionString(connectStr).buildClient();

String containerName = "<YOUR_CONTAINER_NAME>";
BlobContainerClient containerClient = blobServiceClient.getBlobContainerClient(containerName);

String fileToUpload = "optimized.png";
Source source = Tinify.fromUrl("https://tinypng.com/images/panda-happy.png");
source.toFile(fileToUpload);

BlobClient blobClient = containerClient.getBlobClient(fileToUpload);
blobClient.uploadFromFile(fileToUpload);

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. Todos os erros HTTP são convertidos em exceções, que são lançadas pela biblioteca cliente.

Há quatro tipos distintos de erros. A mensagem da exceção conterá uma descrição mais detalhada da condição de erro.

Você pode tratar cada tipo de erro separadamente:

try {
    // Use the Tinify API client.
} catch(AccountException e) {
    System.out.println("The error message is: " + e.getMessage());
    // Verify your API key and account limit.
} catch(ClientException e) {
    // Check your source image and request options.
} catch(ServerException e) {
    // Temporary issue with the Tinify API.
} catch(ConnectionException e) {
    // A network connection error occurred.
} catch(java.lang.Exception e) {
    // Something else went wrong, unrelated to the Tinify API.
}

Se você estiver escrevendo um código que usa uma chave de API configurada pelos seus usuários, talvez queira validar a chave de API antes de tentar comprimir imagens. A validação faz uma requisição fictícia para checar a conexão de rede e verificar a chave de API. Um erro é lançado se a requisição fictícia falhar.

try {
    Tinify.setKey("YOUR_API_KEY");
    Tinify.validate();
} catch(java.lang.Exception e) {
    // Validation of API key failed.
}

Contagem de compressões

O cliente da API registra automaticamente o número de compressões que você fez com sua chave de API neste mês. Você pode obter a contagem de compressões depois de validar sua chave de API ou depois de fazer pelo menos uma requisição de compressão.

int compressionsThisMonth = Tinify.compressionCount();

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.