适用于PHP的Tinify API文档

选择编程语言

Tinify API可用于压缩和优化AVIF、JPEG XL、WebP、JPEG和PNG图片。它被设计为REST服务。多种语言的客户端库让您可以非常轻松地与Tinify API交互。

安装

使用Composer

安装Composer包并将其添加到您应用程序的依赖项中,即可使用PHP客户端:

composer require tinify/tinify

请确保引入Composer的自动加载器:

require_once("vendor/autoload.php");

手动安装

如果您不想使用Composer,也可以手动安装PHP客户端。从GitHub下载Tinify压缩包,将文件解压到您选择的文件夹中,然后按如下所示将其引入您的项目。

require_once("lib/Tinify/Exception.php");
require_once("lib/Tinify/ResultMeta.php");
require_once("lib/Tinify/Result.php");
require_once("lib/Tinify/Source.php");
require_once("lib/Tinify/Client.php");
require_once("lib/Tinify.php");

源代码可在GitHub上获取。

身份验证

要使用API,您必须提供API密钥。您可以通过姓名和电子邮件地址注册来获取API密钥。请始终对您的API密钥保密!请从您的服务器发出请求,而不是从网页发出:API不接受来自其他网站的浏览器请求,而且网页会泄露您的密钥。

\Tinify\setKey("YOUR_API_KEY");

所有请求都必须通过加密的HTTPS连接发出,并使用TLS 1.2或更高版本。

您可以让API客户端通过HTTP代理发出所有请求。请设置您代理服务器的URL,URL中可选择性地包含凭据。

\Tinify\setProxy("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小时内,压缩后的图片可供您下载、调整大小、转换或存储。

您可以选择本地文件作为源,并将其写入另一个文件。

$source = \Tinify\fromFile("unoptimized.webp");
$source->toFile("optimized.webp");

您也可以从缓冲区(包含二进制数据的字符串)上传图片,并获取压缩后的图片数据。

$sourceData = file_get_contents("unoptimized.jpg");
$resultData = \Tinify\fromBuffer($sourceData)->toBuffer();

您可以提供图片的URL,而无需上传图片。

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

调整图片大小

使用API为您上传的图片创建调整大小后的版本。让API处理调整大小,您就无需亲自编写此类代码,并且只需上传一次图片。调整大小后的图片将得到最佳压缩,呈现美观清晰的效果。

您还可以利用智能裁剪功能创建缩略图,聚焦于图片中视觉上最重要的区域。

调整大小会额外计为一次压缩。例如,如果您上传一张图片,并获取优化后的版本以及2个调整大小后的版本,则总共计为3次压缩。

要调整图片大小,请对图片源调用resize方法:

$source = \Tinify\fromFile("large.jpg");
$resized = $source->resize(array(
    "method" => "fit",
    "width" => 150,
    "height" => 100
));
$resized->toFile("thumbnail.jpg");

method描述图片的调整大小方式。可用的方法如下:

scale

按比例缩小图片。您必须提供目标宽度或目标高度,但不能同时提供两者。缩放后的图片将恰好具有所提供的宽度或高度。

调整大小:scale
fit

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

调整大小:fit
cover

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

调整大小:cover
thumb

cover的更高级实现,还能检测具有纯色背景的抠图图片。图片将缩小到您提供的宽度和高度。如果检测到图片中有独立物体,它会在必要时添加更多背景空间或裁剪不重要的部分。

调整大小:thumb

如果目标尺寸大于原始尺寸,图片将不会被放大。禁止放大是为了保护图片的质量。这意味着cover返回的图片可能小于目标尺寸,而thumb仍会在抠图图片周围添加背景,返回目标尺寸的图片。

转换图片

您可以使用API将图片转换为所需的图片类型。Tinify目前支持在AVIF、JPEG XL、WebP、JPEG和PNG之间进行转换。如果您在转换请求中提供了多个图片类型,将返回其中最小的版本。

图片转换会额外计为一次压缩。

$source = \Tinify\fromFile("panda-sticker.jpg");
$converted = $source->convert(array("type" => ["image/webp","image/png"]));
$extension = $converted->result()->extension();
$converted->toFile("panda-sticker." . $extension);

带透明度的图片

只有在您使用transform对象指定一种背景颜色来替换透明部分时,具有透明背景的图片才能被转换为不支持透明度的JPEG。如果未指定背景颜色,当您请求多个图片类型时,将跳过JPEG;而仅请求JPEG时,请求将失败并返回400 Bad Request错误。

如果您希望将透明背景的图片转换为纯色背景的图片,请在transform对象中指定background属性。如果提供了此属性,透明图片的背景将被填充。

$source = \Tinify\fromFile("panda-sticker.png");
$converted = $source->convert(array("type" => "image/jpeg"))->transform(array("background" => "#000000"));
$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方法:

$source = \Tinify\fromFile("unoptimized.jpg");
$copyrighted = $source->preserve("copyright", "creation");
$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方法:

$source = \Tinify\fromFile("unoptimized.jpg");
$source->store(array(
    "service" => "s3",
    "aws_access_key_id" => "AKIAIOSFODNN7EXAMPLE",
    "aws_secret_access_key" => "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region" => "us-west-1",
    "headers" => array("Cache-Control" => "max-age=31536000, public"),
    "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:

$source = \Tinify\fromFile("unoptimized.jpg");
$source->store(array(
    "service" => "gcs",
    "gcp_access_token" => "EXAMPLE_TOKEN_Ag_0HvsglgriGh5_EXAMPLE_TOKEN",
    "headers" => array("Cache-Control" => "max-age=31536000, public"),
    "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,可以使用以下命令进行安装:

composer require aws/aws-sdk-php

存储示例

$source = \Tinify\fromUrl("https://tinypng.com/images/panda-happy.png");
$resultData = $source->toBuffer();

$client = new Aws\S3\S3Client([
  'version' => 'latest',
  'region'  => 'REGION',
  'endpoint' => 'https://YOUR-ENDPOINT.com',
  'credentials' => [
          'key'    => "KEY_EXAMPLE",
          'secret' => "YOUR_SECRET_KEY",
      ],
]);

$client->putObject([
  'Bucket' => 'bucket-name',
  'Key'    => 'file-name.png',
  'Body'   => $resultData,
  'ContentType' => 'image/png'
]);

有关如何使用S3 API的详细文档,请参阅此处。

保存到Microsoft Azure

虽然Tinify API没有提供将图片直接保存到Microsoft Azure存储的集成解决方案,但您仍然可以使用所选开发语言的示例来保存图片。

请注意,您需要使用以下命令安装Azure Storage包:

composer require Microsoft/azure-storage-blob

存储示例

以下示例说明了如何使用Azure存储连接字符串连接到您的Blob容器并上传图片。您可以在Azure存储仪表板上找到连接字符串。

$connectionString = '<YOUR_AZURE_STORAGE_CONNECTION_STRING>';
$blobClient = BlobRestProxy::createBlobService($connectionString);

$containerName = '<YOUR_CONTAINER_NAME>';
$blobClient->getContainer(strtolower($containerName));

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


$content = fopen($fileToUpload, "r");
$blobClient->createBlockBlob($containerName, $fileToUpload, $content);

有关如何使用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(\Tinify\AccountException $e) {
    print("The error message is: " . $e->getMessage());
    // Verify your API key and account limit.
} catch(\Tinify\ClientException $e) {
    // Check your source image and request options.
} catch(\Tinify\ServerException $e) {
    // Temporary issue with the Tinify API.
} catch(\Tinify\ConnectionException $e) {
    // A network connection error occurred.
} catch(Exception $e) {
    // Something else went wrong, unrelated to the Tinify API.
}

如果您编写的代码使用由用户配置的API密钥,您可能需要在尝试压缩图片之前先验证API密钥。验证会发送一个虚拟请求,以检查网络连接并验证API密钥。如果虚拟请求失败,则会抛出错误。

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

压缩次数

API客户端会自动记录本月使用您的API密钥已进行的压缩次数。在验证API密钥或至少发出一次压缩请求后,您即可获取压缩次数。

$compressionsThisMonth = \Tinify\compressionCount();

每次上传计为一次压缩,除非无法再减小文件大小。使用同一API密钥再次上传同一张图片时,在被计数的那次上传之后的8小时内不会再次计数。调整大小、转换或存储压缩后图片的请求会再计为一次压缩,即使该请求同时执行其中多项操作,也只计一次。下载压缩后的图片以及保留元数据都不计为压缩。您的每月压缩限制按账户下所有API密钥的总和计算,因此如果您有多个密钥,每个密钥的压缩次数可能低于您账户的总压缩次数。

获取您的API密钥

您可以在https://tinypng.com/developers获取您的API密钥

需要帮助?有反馈意见?

我们随时为您提供帮助。如果您遇到困难,只需发送邮件至support@tinify.com给我们留言即可。这也是向我们发送所有建议和反馈的理想渠道。