适用于HTTP的Tinify API文档
选择编程语言
Tinify API可用于压缩和优化AVIF、JPEG XL、WebP、JPEG和PNG图片。它被设计为REST服务。本页介绍原始HTTP API。我们还维护多种语言的客户端库,让您可以非常轻松地与Tinify API交互。
该API托管于api.tinify.com
安装
要按照以下示例操作,必须安装curl。使用以下命令验证:
curl --version如果尚未安装,请参阅官方安装说明:
身份验证
要使用API,您必须提供API密钥。您可以通过姓名和电子邮件地址注册来获取API密钥。请始终对您的API密钥保密!请从您的服务器发出请求,而不是从网页发出:API不接受来自其他网站的浏览器请求,而且网页会泄露您的密钥。
API通过HTTP基本身份验证进行身份验证。所有请求都需要一个Authorization标头,其中包含身份验证字符串api:YOUR_API_KEY的Base64编码,YOUR_API_KEY即您可以在API账户页面上找到的密钥。
所有请求都必须通过加密的HTTPS连接发出,并使用TLS 1.2或更高版本。
压缩图片
您可以将任何AVIF、JPEG XL、WebP、JPEG或PNG图片上传到Tinify API进行压缩。我们会自动检测图片类型,并相应地使用TinyPNG或TinyJPG引擎进行优化。您也可以上传HEIC图片,这类图片会被压缩为JPEG。一旦您上传文件或提供图片的URL,压缩便会立即开始。
图片最大可为500MB、2.56亿像素,宽度或高度不得超过150,000像素。在您上传后的8小时内,压缩后的图片可供您下载、调整大小、转换或存储。
从文件上传示例
您可以上传本地文件。POST数据包含图片的二进制数据。
HTTP请求
POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
[binary]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"
}
}例如,如果您在当前目录中有一个名为unoptimized.jpg的文件:
curl https://api.tinify.com/shrink \
--user api:YOUR_API_KEY \
--data-binary @unoptimized.jpg \
--dump-header /dev/stdout从URL上传示例
您也可以提供图片的URL,而无需上传图片。API接受一个JSON请求体,其中将图片URL作为source位置。
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"
}
}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"
}
}例如,如果您的源图片是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下载请求示例
可以使用上一步Location标头中的URL获取压缩后的图片。
HTTP请求
GET /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1HTTP响应
HTTP/1.1 200 OK
Compression-Count: 1
Image-Width: 530
Image-Height: 300
Content-Type: image/jpeg
Content-Length: 46480
[binary]例如,您可以将压缩后的图片保存到名为optimized.jpg的文件中并打开它:
curl https://api.tinify.com/output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp \
--user api:YOUR_API_KEY \
--output optimized.jpg
open optimized.jpg调整图片大小
使用API为您上传的图片创建调整大小后的版本。让API处理调整大小,您就无需亲自编写此类代码,并且只需上传一次图片。调整大小后的图片将得到最佳压缩,呈现美观清晰的效果。
您还可以利用智能裁剪功能创建缩略图,聚焦于图片中视觉上最重要的区域。
调整大小会额外计为一次压缩。例如,如果您上传一张图片,并获取优化后的版本以及2个调整大小后的版本,则总共计为3次压缩。
调整大小请求示例
您可以使用压缩后Location标头中返回的URL来调整图片大小。必须同时提供JSON请求体和Content-Type: application/json标头。
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
}
}HTTP响应
HTTP/1.1 200 OK
Compression-Count: 2
Content-Type: image/jpeg
Image-Width: 150
Image-Height: 85
Content-Length: 12594
[binary]例如,要将调整大小并压缩后的图片保存到名为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请求选项
method描述图片的调整大小方式。可用的方法如下:
- scale
按比例缩小图片。您必须提供目标宽度或目标高度,但不能同时提供两者。缩放后的图片将恰好具有所提供的宽度或高度。

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

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

- thumb
cover的更高级实现,还能检测具有纯色背景的抠图图片。图片将缩小到您提供的宽度和高度。如果检测到图片中有独立物体,它会在必要时添加更多背景空间或裁剪不重要的部分。
如果目标尺寸大于原始尺寸,图片将不会被放大。禁止放大是为了保护图片的质量。这意味着cover返回的图片可能小于目标尺寸,而thumb仍会在抠图图片周围添加背景,返回目标尺寸的图片。
转换图片
您可以使用API将图片转换为所需的图片类型。Tinify目前支持在AVIF、JPEG XL、WebP、JPEG和PNG之间进行转换。如果您在转换请求中提供了多个图片类型,将返回其中最小的版本。
图片转换会额外计为一次压缩。
转换请求示例
HTTP请求
POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json
{
"convert": { "type": "image/webp" }
}HTTP响应
HTTP/1.1 200 OK
Compression-Count: 2
Content-Type: image/webp
Image-Width: 530
Image-Height: 300
Content-Length: 46480
[binary]例如,要将压缩后的PNG或JPEG图片保存为名为panda-sticker.webp的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带透明度的图片
只有在您使用transform对象指定一种背景颜色来替换透明部分时,具有透明背景的图片才能被转换为不支持透明度的JPEG。如果未指定背景颜色,当您请求多个图片类型时,将跳过JPEG;而仅请求JPEG时,请求将失败并返回400 Bad Request错误。
转换和变换请求示例
如果您希望将透明背景的图片转换为纯色背景的图片,请在transform对象中指定background属性。如果提供了此属性,透明图片的背景将被填充。
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"
}
}HTTP响应
HTTP/1.1 200 OK
Compression-Count: 2
Content-Type: image/jpeg
Image-Width: 530
Image-Height: 300
Content-Length: 46480
[binary]例如,如果您有一张透明背景的图片,并希望将其保存为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请求选项
您可以提供以下选项来转换图片:
- convert
您所需的图片类型。以下选项可用作类型:
- 一种图片类型,以字符串
"image/webp"指定。 - 多种图片类型,以数组
["image/webp", "image/jxl", "image/avif"]指定。将返回所提供图片类型中最小的那个。 - 通配符
"*/*"返回Tinify支持的图片类型中最小的那个,目前为WebP、JPEG和PNG。
- 一种图片类型,以字符串
- transform
transform对象指定将应用于图片的样式变换。包含background属性可填充透明图片的背景。以下选项可用于指定背景颜色:
- 十六进制值。使用颜色的六位十六进制值自定义背景颜色,例如:
"#000000"。不支持"#000"这样的三位值。 "white"或"black"。仅支持以字符串形式指定白色和黑色。
如果您希望将透明背景的图片转换为不支持透明度的图片类型(如JPEG),则必须指定背景颜色。
- 十六进制值。使用颜色的六位十六进制值自定义背景颜色,例如:
保留元数据
您可以要求将特定元数据从上传的图片复制到压缩后的版本中。目前支持保留copyright信息、GPSlocation和creation日期。保留元数据会增加压缩后文件的大小,因此您应该只保留重要的元数据。
保留元数据不会计为额外的压缩。不过,系统会在后台重新创建带有附加元数据的图片。
上传请求示例
您需要先上传原始图片,与前面的示例类似。
HTTP请求
POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
[binary]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"
}
}例如,如果您在当前文件夹中有一个名为unoptimized.jpg的文件:
curl https://api.tinify.com/shrink \
--user api:YOUR_API_KEY \
--data-binary @unoptimized.jpg \
--dump-header /dev/stdout带元数据的下载请求示例
现在,您可以下载包含版权信息和创建日期的压缩版图片。指定上一步Location标头中返回的URL,并按如下方式添加JSON指令,通过preserve保留版权信息和创建日期。
HTTP请求
POST /output/2xnsp7jn34e5t16047pvf1xa5f9ty2zp HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
Content-Type: application/json
{
"preserve": ["copyright", "creation"]
}HTTP响应
HTTP/1.1 200 OK
Compression-Count: 1
Content-Type: image/jpeg
Image-Width: 530
Image-Height: 300
Content-Length: 46480
[binary]请注意,Content-Length将略大于第一步输出的size。
以下示例展示了如何将保留了版权元数据的压缩图片保存到名为optimized-copyright.jpg的文件中。
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请求选项
您可以提供以下选项来保留特定元数据。如果上传的图片中不存在所请求的元数据,则不会添加任何元数据。
- 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请求示例
您可以使用Location标头中返回的URL,将压缩后的图片存储到S3。指示将文件存储到S3的请求中必须包含一个含有存储桶信息的JSON请求体,以及Content-Type: application/json标头。
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"
}
}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"
}例如,要将压缩后的图片保存到存储桶example-bucket中名为my-images/optimized.jpg的文件:
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"
}
}'请求选项
要将图片保存到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。组织政策可以强制启用其中任一设置。
GCS请求示例
您可以使用Location标头中返回的URL,将压缩后的图片存储到GCS。指示将文件存储到GCS的请求中必须包含一个含有存储桶信息的JSON请求体,以及Content-Type: application/json标头。
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"
}
}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"
}例如,要将压缩后的图片保存到存储桶example-bucket中名为my-images/optimized.jpg的文件:
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"
}
}'请求选项
要将图片保存到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。
请在页面顶部选择一种编程语言以查看示例代码。
有关如何使用S3 API的详细文档,请参阅此处。
保存到Microsoft Azure
虽然Tinify API没有提供将图片直接保存到Microsoft Azure存储的集成解决方案,但您仍然可以使用所选开发语言的示例来保存图片。
请在页面顶部选择一种编程语言以查看示例代码。
有关如何使用Azure存储API的详细文档,请参阅此处。
错误处理
Tinify API使用HTTP状态码来表示成功或失败。2xx范围内的状态码表示成功。4xx范围内的状态码表示您的请求存在问题。5xx范围内的状态码表示Tinify API出现临时问题。
最常见的错误如下:
400 Bad Request:请求无效,例如包含未知选项,或者图片无法解码或超出限制。请先修改请求,然后再重试。401 Unauthorized:API密钥缺失或无效。404 Not Found:输出URL不存在或已过期。输出URL在您上传图片后的8小时内有效。415 Unsupported Media Type:该文件不是API支持的图片类型。429 Too Many Requests:已达到您的每月压缩限制,或者您发出请求的速度过快。message会说明是哪种情况。对于前一种情况,请等到下一个日历月,或升级您的订阅;对于后一种情况,请在连续请求之间增加一些延迟。该响应不包含Retry-After标头。5xx:Tinify API出现临时问题。几分钟后可以安全地重试该请求。
错误响应示例
如果发生错误,HTTP响应体将包含JSON格式的错误详情。message将包含一段简短的、人类可读的描述。
HTTP请求
POST /shrink HTTP/1.1
Host: api.tinify.comHTTP响应
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": "Unauthorized",
"message": "Credentials are invalid."
}压缩次数
该Web服务会记录您已进行的压缩次数。大多数HTTP响应都包含本月已进行的压缩次数。
响应示例
大多数响应中都包含Compression-Count标头,其中包含使用该API密钥在当前日历月(UTC)内进行的压缩次数。
HTTP请求
POST /shrink HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1
[binary]HTTP响应
HTTP/1.1 201 Created
Compression-Count: 12
[...]每次上传计为一次压缩,除非无法再减小文件大小。使用同一API密钥再次上传同一张图片时,在被计数的那次上传之后的8小时内不会再次计数。调整大小、转换或存储压缩后图片的请求会再计为一次压缩,即使该请求同时执行其中多项操作,也只计一次。下载压缩后的图片以及保留元数据都不计为压缩。您的每月压缩限制按账户下所有API密钥的总和计算,因此如果您有多个密钥,每个密钥的压缩次数可能低于您账户的总压缩次数。
获取您的API密钥
您可以在https://tinypng.com/developers获取您的API密钥
需要帮助?有反馈意见?
我们随时为您提供帮助。如果您遇到困难,只需发送邮件至support@tinify.com给我们留言即可。这也是向我们发送所有建议和反馈的理想渠道。