适用于.NET的Tinify API文档
选择编程语言
Tinify API可用于压缩和优化AVIF、JPEG XL、WebP、JPEG和PNG图片。它被设计为REST服务。多种语言的客户端库让您可以非常轻松地与Tinify API交互。
安装
该客户端目前面向.NET Standard 1.4及更高版本,这意味着它适用于.NET Framework 4.6.1+和.NET Core 1.0+。
安装NuGet包即可使用.NET客户端。
Install-Package Tinify源代码可在GitHub上获取。
该客户端内部只使用异步I/O方法。客户端中几乎所有功能都实现为返回Task<T>的异步方法。由于不存在同步的等效方法,我们决定在所有地方省略Async后缀。
本文档假定您熟悉异步编程(使用C#中的async/await)。
身份验证
要使用API,您必须提供API密钥。您可以通过姓名和电子邮件地址注册来获取API密钥。请始终对您的API密钥保密!请从您的服务器发出请求,而不是从网页发出:API不接受来自其他网站的浏览器请求,而且网页会泄露您的密钥。
using TinifyAPI;
class Example
{
static void Main()
{
Tinify.Key = "YOUR_API_KEY";
}
}所有请求都必须通过加密的HTTPS连接发出,并使用TLS 1.2或更高版本。
您可以让API客户端通过HTTP代理发出所有请求。请设置您代理服务器的URL,URL中可选择性地包含凭据。
Tinify.Proxy = "http://user:pass@192.168.0.1:8080";压缩图片
您可以将任何AVIF、JPEG XL、WebP、JPEG或PNG图片上传到Tinify API进行压缩。我们会自动检测图片类型,并相应地使用TinyPNG或TinyJPG引擎进行优化。您也可以上传HEIC图片,这类图片会被压缩为JPEG。一旦您上传文件或提供图片的URL,压缩便会立即开始。
图片最大可为500MB、2.56亿像素,宽度或高度不得超过150,000像素。在您上传后的8小时内,压缩后的图片可供您下载、调整大小、转换或存储。
您可以选择本地文件作为源,并将其写入另一个文件。
var source = Tinify.FromFile("unoptimized.webp");
await source.ToFile("optimized.webp");您也可以从缓冲区(包含二进制数据的字符串)上传图片,并获取压缩后的图片数据。
var sourceData = File.ReadAllBytes("unoptimized.jpg");
var resultData = await Tinify.FromBuffer(sourceData).ToBuffer();您可以提供图片的URL,而无需上传图片。
var source = Tinify.FromUrl("https://tinypng.com/images/panda-happy.png");
await source.ToFile("optimized.png");调整图片大小
使用API为您上传的图片创建调整大小后的版本。让API处理调整大小,您就无需亲自编写此类代码,并且只需上传一次图片。调整大小后的图片将得到最佳压缩,呈现美观清晰的效果。
您还可以利用智能裁剪功能创建缩略图,聚焦于图片中视觉上最重要的区域。
调整大小会额外计为一次压缩。例如,如果您上传一张图片,并获取优化后的版本以及2个调整大小后的版本,则总共计为3次压缩。
要调整图片大小,请对图片源调用resize方法:
var source = Tinify.FromFile("large.jpg");
var resized = source.Resize(new {
method = "fit",
width = 150,
height = 100
});
await resized.ToFile("thumbnail.jpg");method描述图片的调整大小方式。可用的方法如下:
- scale
按比例缩小图片。您必须提供目标宽度或目标高度,但不能同时提供两者。缩放后的图片将恰好具有所提供的宽度或高度。

- fit
按比例缩小图片,使其适合给定的尺寸。您必须同时提供宽度和高度。缩放后的图片不会超过其中任何一个尺寸。

- cover
按比例缩放图片,并在必要时进行裁剪,使结果恰好具有给定的尺寸。您必须同时提供宽度和高度。图片的哪些部分被裁剪掉是自动确定的。智能算法会确定图片中最重要的区域。

- thumb
cover的更高级实现,还能检测具有纯色背景的抠图图片。图片将缩小到您提供的宽度和高度。如果检测到图片中有独立物体,它会在必要时添加更多背景空间或裁剪不重要的部分。
如果目标尺寸大于原始尺寸,图片将不会被放大。禁止放大是为了保护图片的质量。这意味着cover返回的图片可能小于目标尺寸,而thumb仍会在抠图图片周围添加背景,返回目标尺寸的图片。
转换图片
您可以使用API将图片转换为所需的图片类型。Tinify目前支持在AVIF、JPEG XL、WebP、JPEG和PNG之间进行转换。如果您在转换请求中提供了多个图片类型,将返回其中最小的版本。
图片转换会额外计为一次压缩。
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);带透明度的图片
只有在您使用transform对象指定一种背景颜色来替换透明部分时,具有透明背景的图片才能被转换为不支持透明度的JPEG。如果未指定背景颜色,当您请求多个图片类型时,将跳过JPEG;而仅请求JPEG时,请求将失败并返回400 Bad Request错误。
如果您希望将透明背景的图片转换为纯色背景的图片,请在transform对象中指定background属性。如果提供了此属性,透明图片的背景将被填充。
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");请求选项
您可以提供以下选项来转换图片:
- convert
您所需的图片类型。以下选项可用作类型:
- 一种图片类型,以字符串
"image/webp"指定。 - 多种图片类型,以数组
["image/webp", "image/jxl", "image/avif"]指定。将返回所提供图片类型中最小的那个。 - 通配符
"*/*"返回Tinify支持的图片类型中最小的那个,目前为WebP、JPEG和PNG。
- 一种图片类型,以字符串
- transform
transform对象指定将应用于图片的样式变换。包含background属性可填充透明图片的背景。以下选项可用于指定背景颜色:
- 十六进制值。使用颜色的六位十六进制值自定义背景颜色,例如:
"#000000"。不支持"#000"这样的三位值。 "white"或"black"。仅支持以字符串形式指定白色和黑色。
如果您希望将透明背景的图片转换为不支持透明度的图片类型(如JPEG),则必须指定背景颜色。
- 十六进制值。使用颜色的六位十六进制值自定义背景颜色,例如:
保留元数据
您可以要求将特定元数据从上传的图片复制到压缩后的版本中。目前支持保留copyright信息、GPSlocation和creation日期。保留元数据会增加压缩后文件的大小,因此您应该只保留重要的元数据。
保留元数据不会计为额外的压缩。不过,系统会在后台重新创建带有附加元数据的图片。
要保留特定元数据,请对图片源调用preserve方法:
var source = Tinify.FromFile("large.jpg");
var copyrighted = source.Preserve("copyright", "creation");
await copyrighted.ToFile("optimized-copyright.jpg");您可以提供以下选项来保留特定元数据。如果上传的图片中不存在所请求的元数据,则不会添加任何元数据。
- copyright
保留所有版权信息。这包括EXIF版权标签(JPEG)、XMP权利标签(PNG),以及Photoshop版权标志或URL。最多占用90个额外字节,外加版权数据的长度。
- creation
保留所有创建日期或时间。这是图片或照片最初创建的时刻。这包括EXIF原始日期时间标签(JPEG)或XMP创建时间(PNG)。大约占用70个额外字节。
- location
保留描述图片或照片拍摄地点的所有GPS位置数据。这包括EXIF GPS纬度和GPS经度标签。位置数据只能保留在AVIF、JPEG XL、WebP和JPEG图片中,无法保留在PNG图片中。大约占用130个额外字节。
保存到Amazon S3
您可以让Tinify API将压缩后的图片直接保存到您的Amazon S3。如果您使用S3托管图片,此功能非常有用,您无需将图片下载到服务器再手动上传到S3。存储图片的请求会额外计为一次压缩,即使该请求同时还调整图片大小或转换图片,也只额外计一次。
要将图片保存到S3,请对图片源调用store方法:
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"
});要将图片保存到Amazon S3,您需要提供以下选项:
- service
指定
s3以存储到Amazon S3。
- aws_access_key_id, aws_secret_access_key
您的AWS访问密钥ID和秘密访问密钥。它们是Amazon AWS用户账户的凭据。请在Amazon的文档中了解如何获取它们。该用户必须拥有正确的权限,详情见下文。
- region
您的S3存储桶所在的AWS区域。
- path
您希望存储图片的路径,包括存储桶名称。路径必须采用以下格式:
<bucket>/<path>/<filename>。
以下设置为可选项:
- headers(实验性)
您可以设置所存储图片的
Cache-Control、Content-Disposition和Expires标头。使用Cache-Control来控制浏览器缓存,例如:public, max-age=31536000。完整的指令列表请参阅MDN Web文档。Expires必须是RFC 2822格式的日期,例如:Fri, 01 Jan 2027 00:00:00 GMT。
- acl(可选)
设置一个可选的访问控制列表(ACL)值来管理对象的可访问性。默认情况下,对象被设置为
public-read。使用no-acl可避免发送ACL;对于禁用了ACL的存储桶,必须这样做。新建的S3存储桶默认禁用ACL。有关ACL选项的更多信息,请参阅AWS标准ACL文档。与您的AWS访问密钥ID对应的用户必须对您要创建的对象路径拥有
PutObject权限;除非您使用no-acl,否则还必须拥有PutObjectAcl权限。
S3访问策略示例
如果您想专门为Tinify API创建一个访问权限受限的用户,可以将以下示例策略作为起点:
{
"Statement": {
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::example-bucket/*"
]
}
}保存到Google Cloud Storage
您可以让Tinify API将压缩后的图片直接保存到Google Cloud Storage。如果您使用GCS托管图片,这可以省去您将图片下载到服务器再自行上传到GCS的麻烦。存储图片的请求会额外计为一次压缩,即使该请求同时还调整图片大小或转换图片,也只额外计一次。
在将图片存储到GCS之前,您需要使用服务账号生成访问令牌。
图片以可公开读取的方式存储,使用publicRead预定义ACL。这不适用于启用了统一存储桶级访问权限的存储桶,因为这类存储桶不支持ACL;也不适用于启用了禁止公开访问的存储桶,因为这类存储桶会拒绝公开ACL。组织政策可以强制启用其中任一设置。
生成访问令牌后,您就可以对图片源调用store方法,将优化后的图片直接保存到GCS:
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"
});要将图片保存到Google Cloud Storage,您需要提供以下选项:
- service
指定
gcs以存储到Google Cloud Storage。
- gcp_access_token
用于向Google Cloud Platform进行身份验证的访问令牌。请在Google的身份验证文档中了解如何生成访问令牌。
- path
您希望存储图片的路径,包括存储桶名称。路径必须采用以下格式:
<bucket>/<path>/<filename>。
以下设置为可选项:
- headers(实验性)
您可以设置所存储图片的
Cache-Control和Content-Disposition标头。使用Cache-Control来控制浏览器缓存,例如:public, max-age=31536000。完整的指令列表请参阅MDN Web文档。
保存到S3兼容存储
虽然Tinify API没有提供将图片直接保存到Amazon以外的S3兼容存储提供商的集成解决方案,但您仍然可以使用所选开发语言的示例来保存图片。
DigitalOcean Spaces、Backblaze、G-Core Storage、Wasabi、CenturyLink Object Storage、Filebase等众多存储提供商都使用S3 API。
如果您尚未安装AWS SDK,可以使用以下命令进行安装:
Install-Package AWSSDK.S3存储示例
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);有关如何使用S3 API的详细文档,请参阅此处。
保存到Microsoft Azure
虽然Tinify API没有提供将图片直接保存到Microsoft Azure存储的集成解决方案,但您仍然可以使用所选开发语言的示例来保存图片。
请注意,您需要使用以下命令安装Azure Storage包:
dotnet add package Azure.Storage.Blobs存储示例
以下示例说明了如何使用Azure存储连接字符串连接到您的Blob容器并上传图片。您可以在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);有关如何使用Azure存储API的详细文档,请参阅此处。
错误处理
Tinify API使用HTTP状态码来表示成功或失败。所有HTTP错误都会被转换为异常,并由客户端库抛出。
共有四种不同类型的错误。异常消息将包含对错误情况的更详细描述。
- AccountError
您的API密钥或API账户存在问题。您的请求无法获得授权。如果已达到压缩限制,您可以等到下一个日历月,或升级您的订阅。确认API密钥和账户状态后,您可以重试请求。如果出现超出速率限制的错误,请在连续请求之间增加一些延迟。Tinify设置了宽松的速率限制,以确保为所有客户提供高质量的服务。
- ClientError
由于提交的数据存在问题,请求无法完成。异常消息将包含更多信息。您不应重试该请求。
- ServerError
由于Tinify API出现临时问题,请求无法完成。几分钟后可以安全地重试该请求。如果您在较长时间内反复看到此错误,请联系我们。
- ConnectionError
由于连接Tinify API时出现问题,请求无法发送。您应检查您的网络连接。可以安全地重试该请求。
您可以分别处理每种类型的错误:
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.
}如果您编写的代码使用由用户配置的API密钥,您可能需要在尝试压缩图片之前先验证API密钥。验证会发送一个虚拟请求,以检查网络连接并验证API密钥。如果虚拟请求失败,则会抛出错误。
try {
Tinify.Key = "YOUR_API_KEY";
await Tinify.Validate();
} catch (System.Exception e) {
// Validation of API key failed.
}压缩次数
API客户端会自动记录本月使用您的API密钥已进行的压缩次数。在验证API密钥或至少发出一次压缩请求后,您即可获取压缩次数。
var compressionsThisMonth = Tinify.CompressionCount;每次上传计为一次压缩,除非无法再减小文件大小。使用同一API密钥再次上传同一张图片时,在被计数的那次上传之后的8小时内不会再次计数。调整大小、转换或存储压缩后图片的请求会再计为一次压缩,即使该请求同时执行其中多项操作,也只计一次。下载压缩后的图片以及保留元数据都不计为压缩。您的每月压缩限制按账户下所有API密钥的总和计算,因此如果您有多个密钥,每个密钥的压缩次数可能低于您账户的总压缩次数。
获取您的API密钥
您可以在https://tinypng.com/developers获取您的API密钥
需要帮助?有反馈意见?
我们随时为您提供帮助。如果您遇到困难,只需发送邮件至support@tinify.com给我们留言即可。这也是向我们发送所有建议和反馈的理想渠道。