API Reference

Tinify API让您可以压缩和优化JEPG和PNG图片。 它被设计成一个REST服务。多种语言的客户端程序库，使得使用Tinify API变得非常简单。

安装

把这一行加入到您应用程序的Gemfile中， 就可以用gem形式使用Ruby客户端：

gem "tinify"

源码可以从Github获取。

认证

您必须提供您的API密钥来使用API。您可以通过注册您的姓名和Email地址来获取API密钥。 请秘密保存API密钥。

require "tinify"
Tinify.key = "YOUR_API_KEY"

所有请求必须使用加密的HTTPS连接。

您可以配置API客户端通过HTTP代理发出所有请求。设置代理服务器的URL，包含凭据是可选的。

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

压缩图片

您可以上传任何JPEG或PNG图片到Tinify API来进行压缩。我们将自动检测图片类型并相应的使用TinyPNG或TinyJPG引擎进行优化。 只要上传文件或提供图片URL，就会开始压缩。

您可以选择一个本地文件作为源并写入到另一个文件中。

source = Tinify.from_file("unoptimized.webp")
source.to_file("optimized.webp")

您还可以从缓冲区（buffer）（二进制字符串）上传图片并获取压缩后图片的数据。

source_data = File.read("unoptimized.jpg")
result_data = Tinify.from_buffer(source_data).to_buffer

您可以提供图片的网址，而不必上传图片。

source = Tinify.from_url("https://tinypng.com/images/panda-happy.png")
source.to_file("optimized.png")

调整图片大小

使用API​​创建已上传图像的缩放版本。通过API实现缩放，您可以避免自己编写相关代码，图片只需要上传一次。 缩放后的图片会自动被优化，压缩并且看起来清晰细腻。

您还可以利用智能剪裁功能来创建专注图像中最重要的视觉区域的缩略图。

缩放会计为一次额外的压缩。例如，如果您上传单张图片并且获取优化版本以及两个缩放版本，这将总共被计为3次压缩。

调用图像源的resize方法来缩放图片：

source = Tinify.from_file("large.jpg")
resized = source.resize(
  method: "fit",
  width: 150,
  height: 100
)
resized.to_file("thumbnail.jpg")

在method字段提供图片被缩放的方式。下面是可用的方法：

scale

按比例缩小图片。您必须提供目标width或height，不能同时提供两者。缩小后的图片会有确定的宽度或者高度。

fit

按比例缩小图片，使其适合（fit）给定的尺寸。你必须同时提供width和height。缩小后的图像不会超过这些尺寸中的任何一个。

cover

按比例缩小图片，如有必要裁切图片。结果具有准确的给定尺寸。 图片中哪个部分将被裁切是自动决定的。智能算法确定图像中最重要的区域。

thumb

一个更先进的缩略图实现，还能检测具有简单背景的裁切图片。图片会被缩小到您提供的width和height的大小。 如果一个图片被检测到独立物体，算法将在必要位置添加更多的背景，或者裁切掉不重要的部分。 这是个新功能，我们期待您的反馈！

如果目标尺寸比原始尺寸更大，图片将不会被放大。为了保证图片质量，会避免放大图片。

保留元数据

您可以指定从上传图片拷贝到压缩版本的元数据。当前支持保留版权信息，GPS位置和创建日期。 保留元数据会增加压缩文件的大小，因此您应该只保留重要的元数据。

保留元数据不会算作额外的压缩次数。但是在后台，图像将随着额外的元数据再次创建。

调用图像源的preserve方法来保留特定元数据：

source = Tinify.from_file("unoptimized.jpg")
copyrighted = source.preserve(:copyright, :creation)
copyrighted.to_file("optimized-copyright.jpg")

您可以提供以下选项来保留特定的元数据。如果上传图片没有包含请求的元数据，那么将不会写入新数据。

copyright

保留所有版权信息。包括EXIF版权标记（JPEG），XMP权限标记（PNG）以及Photoshop版权标记或URL。 使用最多90个字节，再加上版权数据的长度。

creation

保留任何创建日期或时间。这是最初创建图像或照片的时刻。包括EXIF原始日期时间标记（JPEG）或XMP创建时间（PNG）。使用大约70个额外字节。

location (JPEG only)

保留任何GPS位置信息，该信息描述图片或者照片创建的位置。包含EXIF GPS维度和GPS精度标签（JPEG）。使用大约130个额外字节。

储存到Amazon S3

您可以告诉Tinify API将压缩后的图片直接储存到Amazon S3。 如果您使用S3托管您的图片，这可以避免您将图像下载到服务器并自行将其上传到S3的麻烦。

要保存图片到S3，在图像源上调用store方法：

source = Tinify.from_file("unoptimized.jpg")
source.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"
)

要将图片储存到Amazon S3，您需要提供如下选项：

service

指定s3来储存到Amazon S3。

aws_access_key_id

aws_secret_access_key

您的AWS访问ID和访问密钥。这些是访问您Amazon AWS用户的凭据。从 文档 中可以找到获取它们的方法。用户必须有正确的权限，请参阅下面的详细信息。

region

指定您S3储存空间的AWS区域。

path

要储存图片的路径，包含空间名称。路径必须按如下格式指定：<bucket>/<path>/<filename>。

如下是可选配置：

headers （实验）

您可以添加Cache-Control请求头来控制储存图片的浏览器缓存，如同以下示例：public, max-age=31536000。 完整的指令列表可以从MDN web文档中找到。

访问ID和访问密钥关联的用户必须拥有要创建对象的路径的PutObject和PutObjectAcl权限。

S3访问策略示例

如果要专门为Tinify API创建访问受限的用户，您可以从以下示例 策略开始：

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

保存到Google云存储

您可以告诉Tinify API将压缩后的图片直接储存到Google云存储。 如果您使用GCS来托管您的图片，这可以避免您将图像下载到服务器并自行将其上传到GCS的麻烦。

在GCS中存储图像之前，您需要使用一个服务帐户生成访问令牌。

require "googleauth"
scopes = ["https://www.googleapis.com/auth/devstorage.read_write"]
authorization = Google::Auth.get_application_default(scopes)
access_token = authorization.fetch_access_token["access_token"]

一旦生成了访问令牌，您就可以通过调用图像源的store方法直接将优化后的图片储存到GCS：

source = Tinify.from_file("unoptimized.jpg")
source.store(
  service: "gcs",
  gcp_access_token: access_token,
  path: "example-bucket/my-images/optimized.jpg"
)

要将图片储存到Google云存储，您需要提供如下选项：

service

指定gcs来储存到Google云存储。

gcp_access_token

向Google云平台认证的授权令牌。从上文查找生成授权令牌的示例。

path

要储存图片的路径，包含空间名称。路径必须按如下格式指定：<bucket>/<path>/<filename>。

如下是可选配置：

headers （实验）

您可以添加Cache-Control请求头来控制储存图片的浏览器缓存，如同以下示例：public, max-age=31536000。 完整的指令列表可以从MDN web文档中找到。

错误处理

Tinify API使用HTTP状态码表示成功或者失败。任何HTTP错误将被转换成异常，异常将由客户端程序库抛出。

有四种类型的错误。异常信息将包含更加详细的错误原因描述。

AccountError

您的API密钥或API帐户存在问题。您的请求无法认证通过。如果达到了您的压缩限制， 您可以等到下一个日历月或升级您的订阅。 验证API密钥和帐户状态后，您可以重试该请求。

ClientError

由于提交的数据存在问题，无法完成请求。异常消息将包含更多信息。您不应该重试该请求。

ServerError

由于Tinify API暂时出现问题，无法完成请求。安全的做法是几分钟后再重试该请求。 如果您在较长时间内反复看到此错误，请与我们联系。

ConnectionError

由于连接问题，请求无法发送到Tinify API。您应该检查网络连接。重试该请求是安全的。

您可以分别处理每种类型的错误：

begin
  # Use the Tinify API client.
rescue Tinify::AccountError => e
  puts "The error message is: " + e.message
  # Verify your API key and account limit.
rescue Tinify::ClientError => e
  # Check your source image and request options.
rescue Tinify::ServerError => e
  # Temporary issue with the Tinify API.
rescue Tinify::ConnectionError => e
  # A network connection error occurred.
rescue => e
  # Something else went wrong, unrelated to the Tinify API.
end

如果您要编写代码使用用户配置的API密钥，您可能希望在尝试压缩图片前验证API密钥。 验证操作发出一个伪请求检查网络连接并且验证API密钥。如果伪请求失败，将抛出一个错误。

begin
  Tinify.key = "YOUR_API_KEY"
  Tinify.validate!
rescue Tinify::Error => e
  # Validation of API key failed.
end

压缩计数

API客户端会自动跟踪您本月所执行的压缩次数。验证API密钥后或在至少发出一次压缩请求后，您可以获得压缩计数。

compressions_this_month = Tinify.compression_count

需要帮助？想要反馈？

我们随时为您提供帮助，如果您遇到了困难，请通过support@tinify.com留言。 它也是向我们发送您所有建议和反馈的绝佳途径。