字节跳动TOS图片处理技能

该技能为存储在字节跳动TOS（海量对象存储）中的文件提供基本的图片处理功能。它允许您直接使用火山引擎TOS SDK获取图片元数据、转换格式、调整大小以及添加水印。

快速开始

1. 客户端初始化

以下Python代码片段演示了如何从环境变量初始化TosClientV2。

python
import os
import tos
from tos.exceptions import TosClientError, TosServerError

def create_client() -> tos.TosClientV2:
使用环境变量中的AK/SK（以及可选的STS令牌）初始化TosClientV2。
try:
ak = os.getenv(TOSACCESSKEY)
sk = os.getenv(TOSSECRETKEY)
endpoint = os.getenv(TOS_ENDPOINT)
region = os.getenv(TOS_REGION)
securitytoken = os.getenv(TOSSECURITY_TOKEN) # 可选，用于STS

if not all([ak, sk, endpoint, region]):
raise ValueError(缺少必要的环境变量（AK、SK、Endpoint、Region）。)

return tos.TosClientV2(
ak=ak,
sk=sk,
endpoint=endpoint,
region=region,
securitytoken=securitytoken,
)
except (ValueError, ImportError) as e:
print(f初始化客户端时出错：{e})
return None

创建客户端

client = create_client()

2. 基本工作流程

python

（假设client已初始化，且bucketname、objectkey已设置）

1. 获取图片信息

try: response = client.getobject(bucketname, object_key, process=image/info) info_data = response.read() print(图片信息：, info_data.decode(utf-8)) except TosServerError as e: print(f获取图片信息时出错：{e})

2. 调整图片大小并保存到本地

try: client.getobjectto_file( bucket_name, object_key, resized_image.jpg, process=image/resize,w500,mlfit # 调整宽度为500像素，lfit模式 ) print(调整大小后的图片已保存到resized_image.jpg) except TosServerError as e: print(f调整图片大小时出错：{e})

3. 将图片转换为WebP格式并保存回TOS

try: response = client.get_object( bucket_name, object_key, process=image/format,fwebp,q80, # 转换为WebP，质量80 save_bucket=my-output-bucket, save_object=processed/image.webp ) save_result = response.read() print(转换后的图片已保存到TOS：, save_result.decode(utf-8)) except TosServerError as e: print(f将转换后的图片保存到TOS时出错：{e})

核心操作

所有图片处理都是通过向getobject或getobjecttofile SDK方法传递process字符串来实现的。

1. 获取图片信息（ImageInfo）

获取图片文件的元数据，例如格式、尺寸和EXIF数据。

SDK方法：client.get_object(..., process=image/info)

python
response = client.getobject(bucketname, object_key, process=image/info)
image_metadata = response.read().decode(utf-8)
print(image_metadata)

2. 转换图片格式（ImageFormat）

将图片转换为不同格式（例如JPEG、PNG、WebP）并调整质量。

SDK方法：client.getobjecttofile(..., process=image/format,fwebp,q_80)

python

转换为PNG格式

client.getobjectto_file(
bucket_name,
object_key,
output.png,
process=image/format,f_png
)

3. 调整图片大小（ImageResize）

根据指定的宽度、高度和调整模式调整图片大小。

SDK方法：client.getobjecttofile(..., process=image/resize,w800,h600,mfill)

python

调整最大宽度为1024像素，保持宽高比

client.getobjectto_file(
bucket_name,
object_key,
resized_1024.jpg,
process=image/resize,w_1024
)

4. 添加水印（ImageWatermark 和 ImageBlindWatermark）

为图片添加可见水印或盲水印。参数较为复杂，应根据官方TOS文档进行构造。

SDK方法：client.getobjectto_file(..., process=image/watermark,...)

python

文本水印示例（参数必须进行Base64编码）

这是一个概念性示例。具体键值请参考官方文档。

import base64
text_b64 = base64.b64encode(我的水印.encode()).decode()
processrule = fimage/watermark,type1,text{textb64},size40,p9

client.getobjectto_file(
bucket_name,
object_key,
watermarked.jpg,
process=process_rule
)

5. 通用图片处理（ImageProcess）

一个灵活的入口点，接受任何有效的图片处理字符串。

SDK方法：client.get_object(..., process=<完整处理字符串>)

python

示例：应用高斯模糊（假设参数）

client.getobjectto_file(
bucket_name,
object_key,
blurred.jpg,
process=image/blur,r5,s2
)

授权认证

认证由tos.TosClientV2处理。通过环境变量提供凭据。

必需的环境变量

• - TOSACCESSKEY
• TOSSECRETKEY
• TOSENDPOINT
• TOSREGION

可选（用于STS）

• - TOSSECURITYTOKEN

最佳实践

• - 错误处理：将SDK调用包裹在try...except块中，以处理TosClientError和TosServerError。
• 参数构造：对于水印等复杂操作，请根据官方TOS文档仔细构造process字符串。在需要时对参数值进行Base64编码。
• 客户端复用：初始化TosClientV2一次，并在多个操作中重复使用。

其他资源

• - 有关每个操作的详细参数，请参阅REFERENCE.md。
• 有关常见的端到端示例，请参阅WORKFLOWS.md。
• 有关可执行的Python示例，请参阅scripts/目录。
• 有关所有处理参数的完整列表，请始终参考官方火山引擎TOS图片处理文档。