SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场byted-tos-image-process

byted-tos-image-process

办公与效率

查看项目

更新于 10-16 14:53

技能介绍

Volcengine TOS Image Process

本技能用于检查和转换存储在火山引擎 TOS（对象存储）中的图片，支持元数据读取、格式转换、缩放、绘制、可见水印、盲水印，以及基于 AI 的图片理解。

使用方式与安装

首次使用时安装依赖：

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

随后用 Python 3.7+ 运行脚本：

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

若出现 tos 的 ModuleNotFoundError，需重新安装依赖。

环境变量

本技能依赖元数据块中声明的 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：可选，保存处理后结果的默认键前缀。

快速开始（常见任务）

读取图片元数据：

python3 {baseDir}/scripts/image_info.py --key photo.jpg

转换为 WebP：

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

缩放到宽度 500：

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

绘制点和连线：

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

通过缩放加裁剪实现放大效果：

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

添加可见文字水印：

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

嵌入盲水印（要求图片不小于 512×512 且账号有权限）：

python3 {baseDir}/scripts/image_blindwatermark.py --key photo.jpg
--kv text=HelloBlind --output blind.jpg

运行自定义 process 字符串：

python3 {baseDir}/scripts/image_process.py --key photo.jpg
--process "image/resize,w_300,h_300,m_fill" --output filled.jpg

预览解析后的请求而不调用 TOS：

python3 {baseDir}/scripts/image_resize.py --key photo.jpg
--width 500 --dry-run --json

对 TOS 图片对象进行 AI 理解（需要白名单）：

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 和裁剪生成适合代理的放大结果。
  • scripts/image_watermark.py：添加可见文字或图片水印，支持定位、旋转、平铺和透明度。
  • scripts/image_blindwatermark.py：嵌入盲水印。需要账号级权限，且图片不小于 512×512 像素。
  • scripts/image_process.py：传入任意原始 image/... process 字符串。
  • scripts/image_understanding.py：通过 VLM（doubao-seed-1.6-vision）对 TOS 图片对象进行 AI 理解。仅当源图片是 TOS 对象时，支持描述、OCR、人脸检测和视觉问答。需要账号白名单。

所有脚本都支持 --key 覆盖 TOS_OBJECT_KEY、--output 保存到本地，以及 --saveas-bucket/--saveas-object 实现 TOS 到 TOS 的持久化。省略 save-as 命令行参数时，使用 TOS_SAVEAS_BUCKET 和 TOS_SAVEAS_OBJECT_PREFIX 作为默认值。多数脚本支持 --json 输出机器可读结果，所有构建 process 的脚本支持 --dry-run 以在不调用 TOS 的情况下预览解析后的请求。用 -h 可查看任一脚本的完整用法。

适用范围之外

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

规则

  • 认证：认证由元数据块中声明的 TOS 身份提供。对象选择可用 --key 按脚本覆盖。
  • 凭据安全：切勿打印凭据环境变量的值，例如 TOS_ACCESS_KEY、TOS_SECRET_KEY、TOS_SECURITY_TOKEN 或模型 API 密钥。应通过直接运行脚本来验证行为，而非回显或导出环境变量。
  • 触发边界：仅当任务涉及火山引擎 TOS 图片对象或 TOS 图片处理工作流时使用本技能。如果用户附带或引用的是普通本地图片或截图，且未提及 TOS，则不要调用这些脚本，改用原生视觉或本地文件能力作答。
  • 试运行：使用 --dry-run --json 验证参数并查看生成的 process 字符串。试运行不调用 TOS，也不需要 AK/SK。如果未提供存储桶或键，试运行会尽可能使用显式占位符；实际执行仍需要有效的 TOS 凭据、存储桶或键以及网络访问。
  • 参数依据：确切的 process 字符串语法以火山引擎 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