volcengine-image-studio

使用该 skill 通过 Volcengine/ARK 兼容的图片生成接口实际生成图片。

中文说明

这是一个面向 火山引擎 / ARK 兼容图片生成接口 的实战型 skill，不只是帮你写提示词，而是直接把图片生成跑起来。

适用场景包括：

• 生成海报、宣传图、配图
• 文生图
• 单张或多张参考图生图
• 直接使用本地图片作为输入
• 一次生成多张结果图
• 自动下载生成结果到本地

默认执行路径

运行打包好的脚本：

python3 scripts/generate_image.py ""

默认情况下，返回的图片 URL 将自动下载至桌面（Desktop）。对于多图生成任务，脚本会为每次运行自动创建一个新文件夹，并使用 Finder 打开该文件夹。

必需配置项

脚本从环境变量中读取配置：

• VOLCENGINE_API_KEY 或 ARK_API_KEY
• VOLCENGINE_MODEL 或 ARK_MODEL
• VOLCENGINE_ENDPOINT 或 ARK_BASE_URL

支持的模式

1. 文生图（Text to image）

python3 scripts/generate_image.py "极简科技海报，深色背景，蓝紫色霓虹光效，高级感"

2. 单张本地参考图 → 生成一张新图

python3 scripts/generate_image.py "生成狗狗趴在草地上的近景画面" 
  --image ~/Desktop/dog-reference.png 
  --sequential-image-generation disabled

3. 单张参考图 URL → 生成一张新图

python3 scripts/generate_image.py "生成狗狗趴在草地上的近景画面" 
  --image "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimage.png" 
  --sequential-image-generation disabled

4. 单张参考图 → 生成多张新图

python3 scripts/generate_image.py "参考这个LOGO，做一套户外运动品牌视觉设计，品牌名称为GREEN，包括包装袋、帽子、纸盒、手环、挂绳等。绿色视觉主色调，趣味、简约现代风格" 
  --image "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimages.png" 
  --sequential-image-generation auto 
  --sequential-max-images 5 
  --stream true

5. 多张参考图 → 生成多张新图

python3 scripts/generate_image.py "生成3张女孩和奶牛玩偶在游乐园开心地坐过山车的图片，涵盖早晨、中午、晚上" 
  --image "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png" 
  --image "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_2.png" 
  --sequential-image-generation auto 
  --sequential-max-images 3 
  --stream true

你也可以传入一个包含 URL 或本地路径的文本文件：

python3 scripts/generate_image.py "根据参考图生成多张变体" --image-file ./refs.txt

本地图片路径支持

• --image ~/Desktop/ref.png → 自动转换为 base64 编码的 data: URL
• --image https://... → 原样发送
• --image data:image/png;base64,... → 原样发送

这使你可以直接使用本地文件，无需手动进行格式转换。

自动下载行为

当 API 返回图片 URL 时，脚本默认将其下载至桌面（Desktop）。

示例下载路径：

• 单张图：~/Desktop/1710000000-my-prompt-1.jpeg
• 多图任务：~/Desktop/1710000000-my-prompt/1710000000-my-prompt-1.jpeg

如需禁用自动下载：

python3 scripts/generate_image.py "极简科技海报" --download-results false

自定义下载目录：

python3 scripts/generate_image.py "极简科技海报" --download-dir ~/Downloads/volcengine

强制为单图任务也创建独立文件夹：

python3 scripts/generate_image.py "极简科技海报" --download-folder-per-run true

禁用按次运行创建文件夹：

python3 scripts/generate_image.py "极简科技海报" --download-folder-per-run false

禁用自动打开 Finder：

python3 scripts/generate_image.py "极简科技海报" --open-download-folder false

可选环境变量

• VOLCENGINE_IMAGE_SIZE（例如：2K）
• VOLCENGINE_IMAGE_COUNT（默认：1）
• VOLCENGINE_IMAGE_QUALITY（默认：standard）
• VOLCENGINE_RESPONSE_FORMAT（默认：url）
• VOLCENGINE_SEQUENTIAL_IMAGE_GENERATION（disabled / auto）
• VOLCENGINE_SEQUENTIAL_MAX_IMAGES（例如：3）
• VOLCENGINE_STREAM（true / false）
• VOLCENGINE_WATERMARK（true / false）
• VOLCENGINE_OUTPUT_DIR（默认：generated-images）
• VOLCENGINE_DOWNLOAD_RESULTS（默认：true）
• VOLCENGINE_DOWNLOAD_DIR（默认：~/Desktop）
• VOLCENGINE_DOWNLOAD_FOLDER_PER_RUN（auto / true / false，默认：auto）
• VOLCENGINE_OPEN_DOWNLOAD_FOLDER（auto / true / false，默认：auto）
• VOLCENGINE_TIMEOUT（默认：120）

执行检查清单

1. 确认提示词内容、目标风格，以及是否需要参考图。
2. 单图参考生成请使用一次 --image；多图参考生成请重复多次 --image 参数。
3. 对于本地图片，可直接传入本地路径；脚本将自动将其转换为 base64 data URL。
4. 对于“单图→多图”或“多参考图”序列任务，请设置 --sequential-image-generation auto 和 --sequential-max-images 。
5. 若 API 返回增量式图片事件（incremental image events），请启用 --stream true。
6. 默认情况下，返回的图片 URL 将下载至桌面；多图任务会自动进入新建的文件夹中。
7. 结果中需明确指出已下载的图片路径或文件夹路径。
8. 对于多图任务，除非用户显式禁用，否则应让 Finder 自动打开所创建的文件夹。
9. 若执行失败，请清晰暴露具体的 HTTP 错误码或缺失字段信息。

版本定位

相比早期仅提供基础生成能力的流程，本版本围绕实践中已被验证可用的逻辑进行了封装：

• 支持 Volcengine / ARK 兼容的接口调用模式
• 支持参考图工作流，包括本地文件直接输入
• 支持串行式多图生成（sequential multi-image generation）
• 支持生成结果自动下载，并按运行（run）分组归档至独立文件夹
• 更契合海报及商业视觉内容生产需求

问题排查

• 密钥缺失 → 设置 VOLCENGINE_API_KEY
• 模型缺失 → 设置 VOLCENGINE_MODEL
• Endpoint 缺失 → 设置 VOLCENGINE_ENDPOINT
• 本地文件未找到 → 检查 --image 指定的路径
• 401/403 → 密钥无效或权限不足
• 404/405 → Endpoint 地址错误
• 400 → 模型、尺寸或请求体与目标 API 不兼容
• 无返回文件/URL → 检查 JSON 输出中的 raw 字段

参考资料

• references/sources.md