字节跳动 TOS 图像处理技能

该技能为存储在字节跳动 TeraObjectStore（TOS）中的文件提供基础图像处理功能。您可直接使用 Volcengine TOS SDK 获取图像元数据、转换格式、调整尺寸以及添加水印。

快速开始

1. 客户端初始化

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

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

def create_client() -> tos.TosClientV2:
    """使用环境变量中的 AK/SK（及可选的 STS token）初始化 TosClientV2。"""
    try:
        ak = os.getenv('TOS_ACCESS_KEY')
        sk = os.getenv('TOS_SECRET_KEY')
        endpoint = os.getenv('TOS_ENDPOINT')
        region = os.getenv('TOS_REGION')
        security_token = os.getenv('TOS_SECURITY_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,
            security_token=security_token,
        )
    except (ValueError, ImportError) as e:
        print(f"客户端初始化失败：{e}")
        return None

# 创建客户端
client = create_client()

2. 基础工作流

# （假设已初始化 'client'，且已设置 'bucket_name' 和 'object_key'）

# 1. 获取图像信息
try:
    response = client.get_object(bucket_name, 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.get_object_to_file(
        bucket_name,
        object_key,
        "resized_image.jpg",
        process="image/resize,w_500,m_lfit" # 调整宽度至 500px，使用 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,f_webp,q_80", # 转为 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}")

核心操作

所有图像处理均通过向 get_object 或 get_object_to_file SDK 方法传入 process 字符串实现。

1. 获取图像信息（ImageInfo）

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

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

response = client.get_object(bucket_name, object_key, process="image/info")
image_metadata = response.read().decode('utf-8')
print(image_metadata)

2. 转换图像格式（ImageFormat）

将图像转换为其他格式（如 JPEG、PNG、WebP），并可调节质量参数。

SDK 方法：client.get_object_to_file(..., process="image/format,f_webp,q_80")

# 转换为 PNG 格式
client.get_object_to_file(
    bucket_name,
    object_key,
    "output.png",
    process="image/format,f_png"
)

3. 调整图像尺寸（ImageResize）

根据指定的宽高及缩放模式对图像进行尺寸调整。

SDK 方法：client.get_object_to_file(..., process="image/resize,w_800,h_600,m_fill")

# 调整至最大宽度 1024px，保持宽高比
client.get_object_to_file(
    bucket_name,
    object_key,
    "resized_1024.jpg",
    process="image/resize,w_1024"
)

4. 添加水印（ImageWatermark 与 ImageBlindWatermark）

为图像添加可见水印或盲水印。相关参数较为复杂，需严格依照官方 TOS 文档构造。

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

# 文本水印示例（参数须经 Base64 编码）
# 此为概念性示例，请参考官方文档确认具体参数键名。
import base64
text_b64 = base64.b64encode("My Watermark".encode()).decode()
process_rule = f"image/watermark,type_1,text_{text_b64},size_40,p_9"

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

5. 通用图像处理（ImageProcess）

一个灵活的入口方法，支持传入任意合法的图像处理字符串。

SDK 方法：client.get_object(..., process="")

# 示例：应用高斯模糊（参数为假设值）
client.get_object_to_file(
    bucket_name,
    object_key,
    "blurred.jpg",
    process="image/blur,r_5,s_2"
)

认证授权

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

必需的环境变量

• TOS_ACCESS_KEY
• TOS_SECRET_KEY
• TOS_ENDPOINT
• TOS_REGION

STS 场景下可选的环境变量

• TOS_SECURITY_TOKEN

最佳实践

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

附加资源

• 各操作的详细参数说明请参阅 REFERENCE.md。
• 常见端到端用例请参阅 WORKFLOWS.md。
• 可执行的 Python 示例请参阅 scripts/ 目录。
• 关于所有图像处理参数的权威列表，请始终查阅 Volcengine 官方 TOS 图像处理文档。