Documentación de la API de Tinify para .NET

Selecciona el lenguaje

La API de Tinify te permite comprimir y optimizar imágenes AVIF, JPEG XL, WebP, JPEG y PNG. Está diseñada como un servicio REST. Las bibliotecas de cliente en varios lenguajes facilitan mucho la interacción con la API de Tinify.

Instalación

Actualmente, el cliente está dirigido a .NET Standard 1.4 y versiones posteriores, lo que significa que funciona con .NET Framework 4.6.1+ y .NET Core 1.0+.

Puedes usar el cliente de .NET instalando el paquete de NuGet.

Install-Package Tinify

El código fuente está disponible en GitHub.

Internamente, el cliente solo utiliza métodos de E/S asíncronos. Casi todo en el cliente está implementado como un método asíncrono que devuelve un Task<T>. Como no existe un equivalente síncrono, hemos decidido omitir el sufijo Async en todas partes.

La documentación da por hecho que estás familiarizado con la programación asíncrona con async/await en C#.

Autenticación

Para usar la API, debes proporcionar tu clave API. Puedes obtener una clave API registrándote con tu nombre y dirección de correo electrónico. ¡Mantén siempre en secreto tu clave API! Realiza tus solicitudes desde tu servidor, no desde una página web: la API no acepta solicitudes que los navegadores envíen desde otros sitios web, y una página web revelaría tu clave.

using TinifyAPI;

class Example
{
  static void Main()
  {
    Tinify.Key = "YOUR_API_KEY";
  }
}

Todas las solicitudes deben realizarse a través de una conexión HTTPS cifrada, con TLS 1.2 o una versión posterior.

Puedes indicar al cliente de la API que realice todas las solicitudes a través de un proxy HTTP. Establece la URL de tu servidor proxy, que opcionalmente puede incluir credenciales.

Tinify.Proxy = "http://user:pass@192.168.0.1:8080";

Comprimir imágenes

Puedes subir cualquier imagen AVIF, JPEG XL, WebP, JPEG o PNG a la API de Tinify para comprimirla. Detectaremos automáticamente el tipo de imagen y la optimizaremos con el motor de TinyPNG o TinyJPG, según corresponda. También puedes subir imágenes HEIC, que se comprimen en formato JPEG. La compresión comenzará en cuanto subas un archivo o proporciones la URL de la imagen.

Las imágenes pueden tener hasta 500 MB y 256 megapíxeles, y como máximo 150 000 píxeles de ancho o de alto. La imagen comprimida está disponible durante 8 horas después de que la subas, para que puedas descargarla, redimensionarla, convertirla o almacenarla.

Puedes elegir un archivo local como origen y escribirlo en otro archivo.

var source = Tinify.FromFile("unoptimized.webp");
await source.ToFile("optimized.webp");

También puedes subir una imagen desde un búfer (una cadena con datos binarios) y obtener los datos de la imagen comprimida.

var sourceData = File.ReadAllBytes("unoptimized.jpg");
var resultData = await Tinify.FromBuffer(sourceData).ToBuffer();

Puedes proporcionar una URL de tu imagen en lugar de tener que subirla.

var source = Tinify.FromUrl("https://tinypng.com/images/panda-happy.png");
await source.ToFile("optimized.png");

Redimensionar imágenes

Usa la API para crear versiones redimensionadas de las imágenes que has subido. Al dejar que la API se encargue del redimensionamiento, no tienes que escribir ese código tú mismo y solo tendrás que subir tu imagen una vez. Las imágenes redimensionadas se comprimirán de forma óptima y tendrán un aspecto bonito y nítido.

También puedes aprovechar el recorte inteligente para crear miniaturas que se centren en las áreas visualmente más importantes de tu imagen.

El redimensionamiento cuenta como una compresión adicional. Por ejemplo, si subes una sola imagen y obtienes la versión optimizada más 2 versiones redimensionadas, contará como 3 compresiones en total.

Para redimensionar una imagen, llama al método resize de un origen de imagen:

var source = Tinify.FromFile("large.jpg");
var resized = source.Resize(new {
    method = "fit",
    width = 150,
    height = 100
});
await resized.ToFile("thumbnail.jpg");

El method describe la forma en que se redimensionará tu imagen. Están disponibles los siguientes métodos:

scale

Reduce la imagen proporcionalmente. Debes proporcionar un ancho o un alto de destino, pero no ambos. La imagen escalada tendrá exactamente el ancho o el alto indicado.

fit

Reduce la imagen proporcionalmente para que quepa dentro de las dimensiones indicadas. Debes proporcionar tanto un ancho como un alto. La imagen escalada no superará ninguna de estas dimensiones.

cover

Escala la imagen proporcionalmente y la recorta si es necesario para que el resultado tenga exactamente las dimensiones indicadas. Debes proporcionar tanto un ancho como un alto. Qué partes de la imagen se recortan se determina automáticamente. Un algoritmo inteligente determina las áreas más importantes de tu imagen.

thumb

Una implementación más avanzada de cover que también detecta imágenes de objetos recortados sobre fondos lisos. La imagen se reduce al ancho y al alto que indiques. Si se detecta una imagen con un objeto independiente, añadirá más espacio de fondo donde sea necesario o recortará las partes poco importantes.

Si las dimensiones de destino son mayores que las dimensiones originales, la imagen no se ampliará. La ampliación se evita para proteger la calidad de tus imágenes. Esto significa que cover puede devolver una imagen más pequeña que las dimensiones de destino, mientras que thumb sigue devolviendo una imagen de objeto recortado con las dimensiones de destino, añadiendo fondo a su alrededor.

Convertir imágenes

Puedes usar la API para convertir tus imágenes al tipo de imagen que desees. Actualmente, Tinify admite la conversión entre AVIF, JPEG XL, WebP, JPEG y PNG. Si indicas más de un tipo de imagen en tu solicitud de conversión, se te devolverá la versión más pequeña.

Convertir una imagen cuenta como una compresión adicional.

var source = Tinify.FromFile("panda-sticker.jpg");
var converted = source.Convert(new {type = new []{"image/webp", "image/png"}});
Result response =  await converted.GetResult();
await converted.ToFile("panda-sticker." + response.Extension);

Imágenes con transparencia

Para convertir una imagen con fondo transparente a JPEG, que no admite transparencia, especifica con el objeto transform un color de fondo que sustituya la transparencia. Sin él, se omite JPEG cuando solicitas más de un tipo de imagen, y si solicitas solo JPEG, la solicitud falla con un error 400 Bad Request.

Si quieres convertir una imagen con fondo transparente en una con fondo sólido, especifica una propiedad background en el objeto transform. Si se proporciona esta propiedad, se rellenará el fondo de la imagen transparente.

var source = Tinify.FromFile("panda-sticker.png");
var converted = source.Convert(new {type = "image/jpeg"}).Transform(new {background = "#000000"});
await converted.ToFile("panda-sticker.jpg");

Opciones de la solicitud

Puedes proporcionar las siguientes opciones para convertir tu imagen:

Conservar los metadatos

Puedes solicitar que se copien metadatos específicos de la imagen subida a la versión comprimida. Actualmente se admite conservar la información de derechos de autor (copyright), la ubicación GPS (location) y la fecha de creación (creation). Conservar metadatos aumenta el tamaño del archivo comprimido, por lo que solo deberías conservar los metadatos que sea importante mantener.

Conservar metadatos no contará como una compresión adicional. Sin embargo, en segundo plano la imagen se volverá a crear con los metadatos adicionales.

Para conservar metadatos específicos, llama al método preserve de un origen de imagen:

var source = Tinify.FromFile("large.jpg");
var copyrighted = source.Preserve("copyright", "creation");
await copyrighted.ToFile("optimized-copyright.jpg");

Puedes proporcionar las siguientes opciones para conservar metadatos específicos. No se añadirá ningún metadato si los metadatos solicitados no están presentes en la imagen subida.

Guardar en Amazon S3

Puedes pedir a la API de Tinify que guarde las imágenes comprimidas directamente en tu Amazon S3. Esta función es útil si usas S3 para alojar imágenes, ya que elimina la necesidad de descargarlas a tu servidor y subirlas manualmente a S3. Una solicitud que almacena una imagen cuenta como una sola compresión adicional, incluso cuando también redimensiona o convierte la imagen.

Para guardar una imagen en S3, llama al método store de un origen de imagen:

var source = Tinify.FromFile("large.jpg");
await source.Store(new {
    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"
});

Debes proporcionar las siguientes opciones para guardar una imagen en Amazon S3:

Los siguientes ajustes son opcionales:

Ejemplo de política de acceso a S3

Si quieres crear un usuario con acceso limitado específicamente para la API de Tinify, puedes usar la siguiente política de ejemplo como punto de partida:

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

Guardar en Google Cloud Storage

Puedes indicar a la API de Tinify que guarde las imágenes comprimidas directamente en Google Cloud Storage. Si usas GCS para alojar tus imágenes, te ahorras la molestia de descargar las imágenes a tu servidor y subirlas tú mismo a GCS. Una solicitud que almacena una imagen cuenta como una sola compresión adicional, incluso cuando también redimensiona o convierte la imagen.

Antes de poder almacenar una imagen en GCS, tendrás que generar un token de acceso con una cuenta de servicio.

Las imágenes se almacenan con acceso público de lectura, mediante la ACL predefinida publicRead. Esto no funciona con los buckets que tienen acceso uniforme a nivel de bucket, que no admiten ACL, ni con los que tienen la prevención de acceso público, que rechazan las ACL públicas. Una política de la organización puede imponer cualquiera de los dos ajustes.

Una vez que hayas generado el token de acceso, puedes guardar la imagen optimizada directamente en GCS llamando al método store de un origen de imagen:

var source = Tinify.FromFile("large.jpg");
await source.Store(new {
    service = "gcs",
    gcp_access_token = "EXAMPLE_TOKEN_Ag_0HvsglgriGh5_ZmgUBmjaoGU_EXAMPLE_TOKEN",
    path = "example-bucket/my-images/optimized.jpg"
});

Debes proporcionar las siguientes opciones para guardar una imagen en Google Cloud Storage:

Los siguientes ajustes son opcionales:

Guardar en almacenamiento compatible con S3

Aunque la API de Tinify no ofrece una solución integrada para guardar las imágenes directamente en proveedores de almacenamiento compatibles con S3 distintos de Amazon, puedes guardar tus imágenes usando el ejemplo para el lenguaje de desarrollo que hayas elegido.

La API de S3 la utilizan proveedores de almacenamiento como DigitalOcean Spaces, Backblaze, G-Core Storage, Wasabi, CenturyLink Object Storage, Filebase y muchos otros.

Si aún no tienes instalado el SDK de AWS, puedes añadirlo con el siguiente comando:

Install-Package AWSSDK.S3

Ejemplo de almacenamiento

var source = Tinify.FromUrl("https://tinypng.com/images/panda-happy.png");
var result = await source.ToBuffer();

AmazonS3Config config = new AmazonS3Config();
config.ServiceURL = "https://YOUR-ENDPOINT.com";

AmazonS3Client s3Client = new AmazonS3Client(
  "ACCESS_KEY_EXAMPLE",
  "YOUR_SECRET_KEY",
  config
  );

PutObjectRequest request = new PutObjectRequest();
request.BucketName  = "bucket-name";
request.Key         = "file-name.png";
request.ContentType = "image/png";
request.InputStream = new MemoryStream(result);

await s3Client.PutObjectAsync(request);

La documentación detallada sobre cómo usar la API de S3 se encuentra aquí.

Guardar en Microsoft Azure

Aunque la API de Tinify no ofrece una solución integrada para guardar las imágenes directamente en el almacenamiento de Microsoft Azure, puedes guardar tus imágenes usando el ejemplo para el lenguaje de desarrollo que hayas elegido.

Ten en cuenta que tendrás que instalar el paquete de Azure Storage con el siguiente comando:

dotnet add package Azure.Storage.Blobs

Ejemplo de almacenamiento

El siguiente ejemplo explica cómo conectarte a tu contenedor de blobs y subir tu imagen usando la cadena de conexión de tu almacenamiento de Azure. Encontrarás tu cadena de conexión en el panel de control de tu almacenamiento de Azure.

var connectStr = "<YOUR_AZURE_STORAGE_CONNECTION_STRING>";
var blobServiceClient = new BlobServiceClient(connectStr);

var containerName = "<YOUR_CONTAINER_NAME>";
var containerClient = blobServiceClient.GetBlobContainerClient(containerName);

var fileToUpload = "optimized.png";
var source = Tinify.FromUrl("https://tinypng.com/images/panda-happy.png");
await source.ToFile(fileToUpload);

var blobClient = containerClient.GetBlobClient(fileToUpload);
await blobClient.UploadAsync(fileToUpload, true);

La documentación detallada sobre cómo usar la API de almacenamiento de Azure se encuentra aquí.

Gestión de errores

La API de Tinify utiliza códigos de estado HTTP para indicar si una solicitud se ha realizado correctamente o no. Todos los errores HTTP se convierten en excepciones, que lanza la biblioteca de cliente.

Hay cuatro tipos distintos de errores. El mensaje de la excepción contendrá una descripción más detallada de la condición de error.

Puedes gestionar cada tipo de error por separado:

try
{
    // Use the Tinify API client.
}
catch (AccountException e)
{
    System.Console.WriteLine("The error message is: " + e.Message);
    // 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 (System.Exception e)
{
    // Something else went wrong, unrelated to the Tinify API.
}

Si estás escribiendo código que usa una clave API configurada por tus usuarios, quizá quieras validar la clave API antes de intentar comprimir imágenes. La validación realiza una solicitud de prueba para comprobar la conexión de red y verificar la clave API. Si la solicitud de prueba falla, se lanza un error.

try {
    Tinify.Key = "YOUR_API_KEY";
    await Tinify.Validate();
} catch (System.Exception e) {
    // Validation of API key failed.
}

Número de compresiones

El cliente de la API lleva automáticamente la cuenta del número de compresiones que has realizado con tu clave API este mes. Puedes obtener el número de compresiones después de haber validado tu clave API o después de haber realizado al menos una solicitud de compresión.

var compressionsThisMonth = Tinify.CompressionCount;

Cada subida cuenta como una compresión, salvo que no se pueda reducir más el tamaño del archivo. Si vuelves a subir la misma imagen con la misma clave API, no cuenta durante las 8 horas siguientes a la subida que sí contó. Una solicitud que redimensiona, convierte o almacena la imagen comprimida cuenta como una compresión más, incluso cuando hace varias de estas operaciones a la vez. No cuentan la descarga de la imagen comprimida ni la conservación de metadatos. Tu límite mensual se aplica a todas las claves API de tu cuenta en conjunto, por lo que, si tienes más de una clave, el recuento de cada clave puede ser inferior al total de tu cuenta.

Obtén tu clave API

Puedes obtener tu clave API en https://tinypng.com/developers

¿Necesitas ayuda? ¿Comentarios?

Siempre estamos aquí para ayudarte, así que si te quedas atascado, escríbenos a support@tinify.com. También es el lugar perfecto para enviarnos todas tus sugerencias y comentarios.