byted-tos-image-process

Volcengine TOS 图像处理

检查并转换存储在 Volcengine TOS 中的图像，包括元数据、格式转换、调整尺寸、水印、盲水印和 AI 图像理解。

设置（每个环境仅需一次）

首次使用时安装依赖：

cd {baseDir}
pip install -r {baseDir}/requirements.txt

然后使用 Python 3.7+ 运行脚本：

python3 {baseDir}/scripts/<script>.py <args>

如果遇到 ModuleNotFoundError，且错误指向 tos，请重新安装依赖。

环境变量

此技能依赖 metadata 块中声明的 TOS 身份信息。常见的运行时变量如下：

环境变量	必填	描述
TOS_ACCESS_KEY	是	TOS 访问密钥 ID
TOS_SECRET_KEY	是	TOS 访问密钥
TOS_ENDPOINT	是	TOS 终端节点 URL
TOS_REGION	是	TOS 区域
TOS_BUCKET	是	存储图像的源存储桶
TOS_OBJECT_KEY	否	图像的源对象键。可通过 --key 覆盖
TOS_SECURITY_TOKEN	否	使用临时凭证时的 STS 会话令牌
TOS_SAVEAS_BUCKET	否	保存处理结果的默认目标存储桶
TOS_SAVEAS_OBJECT_PREFIX	否	保存处理结果的默认对象键前缀

快速开始（常见任务）

# Read image metadata
python3 {baseDir}/scripts/image_info.py --key photo.jpg

# Convert to WebP
python3 {baseDir}/scripts/image_format.py --key photo.jpg --f webp --output converted.webp

# Resize to width 500
python3 {baseDir}/scripts/image_resize.py --key photo.jpg --width 500 --output resized.jpg

# Draw points and connecting lines
python3 {baseDir}/scripts/image_draw.py --key photo.jpg \
  --points 50x50-200x120-320x220 --line --color FF0000 --output draw.jpg

# Zoom by resize + crop
python3 {baseDir}/scripts/image_zoom.py --key photo.jpg \
  --resize-w 1200 --crop-w 500 --crop-h 400 --gravity center --output zoom.jpg

# Add visible text watermark
python3 {baseDir}/scripts/image_watermark.py --key photo.jpg \
  --text "My Brand" --font fangzhengshusong --color FF0000 --size 72 \
  --gravity center --output watermarked.jpg

# Embed blind watermark (requires ≥512×512 image and account permission)
python3 {baseDir}/scripts/image_blindwatermark.py --key photo.jpg \
  --kv text=HelloBlind --output blind.jpg

# Run a custom process string
python3 {baseDir}/scripts/image_process.py --key photo.jpg \
  --process "image/resize,w_300,h_300,m_fill" --output filled.jpg

# Preview the resolved request without calling TOS
python3 {baseDir}/scripts/image_resize.py --key photo.jpg \
  --width 500 --dry-run --json

# AI-powered understanding for a TOS image object (requires whitelist)
python3 {baseDir}/scripts/image_understanding.py --key photo.jpg \
  --prompt "Describe this image in detail"
python3 {baseDir}/scripts/image_understanding.py --key document.png \
  --prompt "识别图片中的所有文字内容"

可用脚本

脚本	用途
scripts/image_info.py	读取图像元数据（格式、尺寸、大小）。如果 TOS 返回原始字节，则回退到本地解析。
scripts/image_format.py	转换格式（jpg、png、webp），并可选择设置质量。
scripts/image_resize.py	按宽度、高度或模式调整尺寸。
scripts/image_draw.py	使用 image/draw 在图像上绘制点，并可选择绘制连接线。
scripts/image_zoom.py	通过串联 image/resize 和 crop，生成便于 Agent 使用的缩放结果。
scripts/image_watermark.py	添加可见文字或图像水印，并设置位置、旋转、平铺和不透明度。
scripts/image_blindwatermark.py	嵌入盲水印。需要账户级权限，且图像尺寸须不小于 512×512 px。
scripts/image_process.py	传入任意原始 image/... 处理字符串。
scripts/image_understanding.py	通过 VLM（doubao-seed-1.6-vision）对 TOS 图像对象进行 AI 理解。仅当源图像是 TOS 对象时，才支持描述、OCR、人脸检测和视觉问答。需要加入账户白名单。

所有脚本均支持 --key，用于覆盖 TOS_OBJECT_KEY；支持 --output，用于本地保存；还支持 --saveas-bucket/--saveas-object，用于在 TOS 之间持久化结果。省略保存为 CLI 参数时，默认使用 TOS_SAVEAS_BUCKET 和 TOS_SAVEAS_OBJECT_PREFIX。大多数脚本支持 --json，以输出机器可读的结果；所有构建处理请求的脚本均支持 --dry-run，可在不调用 TOS 的情况下预览解析后的请求。使用 -h 运行任意脚本可查看完整用法。

不适用范围

• 使用 TOS 以外的本地桌面工具编辑图像。
• 不涉及 TOS 存储桶/对象键的普通上传截图、本地图像文件、移动端 UI 截图、通用 OCR、人脸检测和视觉问答。请改用模型原生视觉能力或本地文件工具。
• 视频或文档处理（请使用 byted-tos-video-process 或 byted-tos-doc-process）。
• 非 TOS 存储服务商。

规则

• 身份验证：身份验证由上方 metadata 块中声明的 TOS 身份提供。可以使用 --key 按脚本覆盖对象选择。
• 凭据安全：切勿打印凭据环境变量的值，例如 TOS_ACCESS_KEY、TOS_SECRET_KEY、TOS_SECURITY_TOKEN 或模型 API 密钥。请直接运行脚本来验证行为，不要回显或转储环境变量。
• 触发范围：仅在处理 Volcengine TOS 图像对象或 TOS 图像处理工作流时使用此技能。如果用户附加或引用了普通本地图像/截图，且未提及 TOS，请勿调用这些脚本；改用原生视觉/本地文件能力作答。
• 试运行：使用 --dry-run --json 验证参数并检查生成的 process 字符串。试运行不会调用 TOS，也不需要 AK/SK。如果未提供 bucket/key，试运行会尽可能使用明确的占位符；实际执行仍需要有效的 TOS 凭据、bucket/key 和网络访问。
• 参数的权威来源：process 字符串的确切语法以 Volcengine TOS 官方文档为准。如有疑问，请查阅 REFERENCE.md。
• 水印编码：image/watermark 中的文本和字体参数需要使用 URL 安全的 Base64 编码。使用 --text 和 --font 时，水印脚本会自动处理。
• 盲水印限制：源图像至少需要 512×512 像素，并且账号必须已启用盲水印功能。如果缺少此功能，脚本会以 [SKIP] 退出（使用 --strict 可直接报错）。
• 图像理解：仅针对 TOS 图像对象，使用 image/understanding 和 doubao-seed-1.6-vision VLM 模型。--prompt 参数为必填项。需要账号已加入白名单。响应时间通常为 10-60 秒。
• 语言：使用用户首选语言回复。

延伸阅读

• 设置和环境：README.md
• 参数参考：REFERENCE.md
• 端到端工作流：WORKFLOWS.md