Documentation de l’API Tinify pour .NET

Choisir un langage

L’API Tinify vous permet de compresser et d’optimiser des images AVIF, JPEG XL, WebP, JPEG et PNG. Elle est conçue comme un service REST. Les bibliothèques clientes disponibles dans différents langages permettent d’interagir très facilement avec l’API Tinify.

Installation

Le client cible actuellement .NET Standard 1.4 et les versions ultérieures, ce qui signifie qu’il fonctionne avec .NET Framework 4.6.1+ et .NET Core 1.0+.

Vous pouvez utiliser le client .NET en installant le paquet NuGet.

Install-Package Tinify

Le code source est disponible sur GitHub.

En interne, le client utilise uniquement des méthodes d’E/S asynchrones. Presque tout, dans le client, est implémenté sous forme de méthode asynchrone qui renvoie un Task<T>. Comme il n’existe aucun équivalent synchrone, nous avons décidé d’omettre partout le suffixe Async.

La documentation part du principe que vous connaissez bien la programmation asynchrone avec async/await en C#.

Authentification

Pour utiliser l’API, vous devez fournir votre clé API. Vous pouvez obtenir une clé API en vous inscrivant avec votre nom et votre adresse e-mail. Gardez toujours votre clé API secrète ! Effectuez vos requêtes depuis votre serveur, et non depuis une page web : l’API n’accepte pas les requêtes envoyées par les navigateurs depuis d’autres sites web, et une page web révélerait votre clé.

using TinifyAPI;

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

Toutes les requêtes doivent passer par une connexion HTTPS chiffrée, avec TLS 1.2 ou une version ultérieure.

Vous pouvez demander au client API d’effectuer toutes les requêtes via un proxy HTTP. Indiquez l’URL de votre serveur proxy, qui peut éventuellement inclure des identifiants.

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

Compression des images

Vous pouvez téléverser n’importe quelle image AVIF, JPEG XL, WebP, JPEG ou PNG vers l’API Tinify pour la compresser. Nous détectons automatiquement le type d’image et l’optimisons en conséquence avec le moteur TinyPNG ou TinyJPG. Vous pouvez également téléverser des images HEIC, qui sont compressées au format JPEG. La compression commence dès que vous téléversez un fichier ou fournissez l’URL de l’image.

Les images peuvent atteindre 500 Mo et 256 mégapixels, et mesurer au maximum 150 000 pixels de largeur ou de hauteur. L’image compressée est disponible pendant 8 heures après le téléversement, pour que vous puissiez la télécharger, la redimensionner, la convertir ou la stocker.

Vous pouvez choisir un fichier local comme source et l’enregistrer dans un autre fichier.

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

Vous pouvez également téléverser une image depuis un tampon (une chaîne contenant des données binaires) et récupérer les données de l’image compressée.

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

Vous pouvez fournir l’URL de votre image au lieu de devoir la téléverser.

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

Redimensionnement des images

Utilisez l’API pour créer des versions redimensionnées des images que vous avez téléversées. En confiant le redimensionnement à l’API, vous n’avez pas à écrire ce code vous-même et vous n’avez à téléverser votre image qu’une seule fois. Les images redimensionnées seront compressées de manière optimale, avec un rendu net et agréable.

Vous pouvez également tirer parti du recadrage intelligent pour créer des vignettes centrées sur les zones visuellement les plus importantes de votre image.

Le redimensionnement compte comme une compression supplémentaire. Par exemple, si vous téléversez une seule image et récupérez la version optimisée ainsi que 2 versions redimensionnées, cela comptera comme 3 compressions au total.

Pour redimensionner une image, appelez la méthode resize sur une source d’image :

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

Le paramètre method décrit la manière dont votre image sera redimensionnée. Les méthodes suivantes sont disponibles :

scale

Réduit l’image proportionnellement. Vous devez fournir soit une largeur cible, soit une hauteur cible, mais pas les deux. L’image redimensionnée aura exactement la largeur ou la hauteur indiquée.

fit

Réduit l’image proportionnellement pour qu’elle tienne dans les dimensions indiquées. Vous devez fournir à la fois une largeur et une hauteur. L’image redimensionnée ne dépassera aucune de ces dimensions.

cover

Redimensionne l’image proportionnellement et la recadre si nécessaire pour que le résultat ait exactement les dimensions indiquées. Vous devez fournir à la fois une largeur et une hauteur. Les parties de l’image supprimées par le recadrage sont déterminées automatiquement. Un algorithme intelligent détermine les zones les plus importantes de votre image.

thumb

Une implémentation plus avancée de cover, qui détecte également les images détourées sur fond uni. L’image est réduite à la largeur et à la hauteur que vous indiquez. Si une image contenant un objet isolé est détectée, la méthode ajoute davantage d’espace d’arrière-plan si nécessaire ou recadre les parties sans importance.

Si les dimensions cibles sont supérieures aux dimensions d’origine, l’image ne sera pas agrandie. L’agrandissement est empêché afin de préserver la qualité de vos images. Cela signifie que cover peut renvoyer une image plus petite que les dimensions cibles, tandis que thumb renvoie tout de même une image détourée aux dimensions cibles en ajoutant de l’arrière-plan autour d’elle.

Conversion des images

Vous pouvez utiliser l’API pour convertir vos images dans le type d’image de votre choix. Tinify prend actuellement en charge la conversion entre AVIF, JPEG XL, WebP, JPEG et PNG. Si vous indiquez plusieurs types d’image dans votre requête de conversion, la version la plus petite vous sera renvoyée.

La conversion d’une image compte comme une compression supplémentaire.

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);

Images avec transparence

Les images à fond transparent ne peuvent être converties au format JPEG, qui ne prend pas en charge la transparence, que si vous indiquez, à l’aide de l’objet transform, une couleur de fond qui remplace la transparence. Sans couleur de fond, le format JPEG est exclu lorsque vous demandez plusieurs types d’image, et une requête portant uniquement sur le format JPEG échoue avec une erreur 400 Bad Request.

Si vous souhaitez convertir une image à fond transparent en une image à fond uni, indiquez une propriété background dans l’objet transform. Si cette propriété est fournie, le fond d’une image transparente sera rempli.

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");

Options de la requête

Vous pouvez fournir les options suivantes pour convertir votre image :

Conservation des métadonnées

Vous pouvez demander que certaines métadonnées soient copiées de l’image téléversée vers la version compressée. La conservation des informations de copyright, de la location GPS et de la date de creation est actuellement prise en charge. La conservation des métadonnées augmente la taille du fichier compressé : ne conservez donc que les métadonnées qu’il est important de garder.

La conservation des métadonnées ne compte pas comme une compression supplémentaire. Toutefois, en arrière-plan, l’image sera recréée avec les métadonnées supplémentaires.

Pour conserver certaines métadonnées, appelez la méthode preserve sur une source d’image :

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

Vous pouvez fournir les options suivantes pour conserver certaines métadonnées. Aucune métadonnée ne sera ajoutée si les métadonnées demandées sont absentes de l’image téléversée.

Enregistrement sur Amazon S3

Vous pouvez demander à l’API Tinify d’enregistrer les images compressées directement sur votre Amazon S3. Cette fonctionnalité est utile si vous utilisez S3 pour héberger vos images : vous n’avez plus besoin de les télécharger sur votre serveur, puis de les téléverser manuellement sur S3. Une requête qui stocke une image compte comme une compression supplémentaire, même si elle redimensionne ou convertit également l’image.

Pour enregistrer une image sur S3, appelez la méthode store sur une source d’image :

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"
});

Vous devez fournir les options suivantes pour enregistrer une image sur Amazon S3 :

Les paramètres suivants sont facultatifs :

Exemple de stratégie d’accès S3

Si vous souhaitez créer un utilisateur à accès limité spécifiquement pour l’API Tinify, vous pouvez partir de l’exemple de stratégie suivant :

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

Enregistrement sur Google Cloud Storage

Vous pouvez demander à l’API Tinify d’enregistrer les images compressées directement sur Google Cloud Storage. Si vous utilisez GCS pour héberger vos images, cela vous évite de devoir télécharger les images sur votre serveur, puis de les téléverser vous-même sur GCS. Une requête qui stocke une image compte comme une compression supplémentaire, même si elle redimensionne ou convertit également l’image.

Avant de pouvoir stocker une image dans GCS, vous devrez générer un jeton d’accès avec un compte de service.

Les images sont stockées de façon à être lisibles publiquement, avec l’ACL prédéfinie publicRead. Cela ne fonctionne pas avec les compartiments qui utilisent l’accès uniforme au niveau du bucket, car ils ne prennent pas en charge les ACL, ni avec ceux soumis à la protection contre l’accès public, qui refusent les ACL publiques. Une règle d’administration de l’organisation peut imposer l’un ou l’autre de ces paramètres.

Une fois le jeton d’accès généré, vous pouvez enregistrer l’image optimisée directement sur GCS en appelant la méthode store sur une source d’image :

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"
});

Vous devez fournir les options suivantes pour enregistrer une image sur Google Cloud Storage :

Les paramètres suivants sont facultatifs :

Enregistrement sur un stockage compatible S3

Bien que l’API Tinify ne propose pas de solution intégrée pour enregistrer les images directement chez des fournisseurs de stockage compatibles S3 autres qu’Amazon, vous pouvez tout de même enregistrer vos images à l’aide de l’exemple correspondant au langage de développement de votre choix.

L’API S3 est utilisée par des fournisseurs de stockage tels que DigitalOcean Spaces, Backblaze, G-Core Storage, Wasabi, CenturyLink Object Storage, Filebase et bien d’autres.

Si le SDK AWS n’est pas encore installé, vous pouvez l’ajouter avec la commande suivante :

Install-Package AWSSDK.S3

Exemple de stockage

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 documentation détaillée sur l’utilisation de l’API S3 est disponible ici.

Enregistrement sur Microsoft Azure

Bien que l’API Tinify ne propose pas de solution intégrée pour enregistrer les images directement dans le stockage Microsoft Azure, vous pouvez tout de même enregistrer vos images à l’aide de l’exemple correspondant au langage de développement de votre choix.

N’oubliez pas que vous devrez installer le paquet Azure Storage avec la commande suivante :

dotnet add package Azure.Storage.Blobs

Exemple de stockage

L’exemple suivant explique comment vous connecter à votre conteneur de blobs et téléverser votre image à l’aide de la chaîne de connexion de votre stockage Azure. Votre chaîne de connexion se trouve dans le tableau de bord de votre stockage 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 documentation détaillée sur l’utilisation de l’API de stockage Azure est disponible ici.

Gestion des erreurs

L’API Tinify utilise les codes de statut HTTP pour indiquer la réussite ou l’échec. Toutes les erreurs HTTP sont converties en exceptions, qui sont levées par la bibliothèque cliente.

Il existe quatre types d’erreurs distincts. Le message de l’exception contiendra une description plus détaillée de l’erreur.

Vous pouvez gérer chaque type d’erreur séparément :

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 vous écrivez du code qui utilise une clé API configurée par vos utilisateurs, vous voudrez peut-être valider la clé API avant de tenter de compresser des images. La validation effectue une requête fictive pour tester la connexion réseau et vérifier la clé API. Une erreur est levée si la requête fictive échoue.

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

Nombre de compressions

Le client API comptabilise automatiquement le nombre de compressions que vous avez effectuées avec votre clé API ce mois-ci. Vous pouvez obtenir le nombre de compressions après avoir validé votre clé API ou après avoir effectué au moins une requête de compression.

var compressionsThisMonth = Tinify.CompressionCount;

Chaque téléversement compte comme une compression, sauf si la taille du fichier ne peut pas être réduite davantage. Si vous téléversez à nouveau la même image avec la même clé API, elle n’est pas comptabilisée pendant les 8 heures qui suivent le téléversement comptabilisé. Une requête qui redimensionne, convertit ou stocke l’image compressée compte comme une compression de plus, même si elle effectue plusieurs de ces opérations à la fois. Le téléchargement de l’image compressée et la conservation des métadonnées ne sont pas comptabilisés. Votre limite mensuelle s’applique à toutes les clés API de votre compte réunies : si vous avez plusieurs clés, le nombre de compressions de chaque clé peut donc être inférieur au total de votre compte.

Obtenez votre clé API

Vous pouvez récupérer votre clé API sur https://tinypng.com/developers

Besoin d’aide ? Des commentaires ?

Nous sommes toujours là pour vous aider : si vous êtes bloqué, écrivez-nous simplement à support@tinify.com. C’est aussi l’endroit idéal pour nous envoyer toutes vos suggestions et vos commentaires.