volcano-image-generator

name	volcano-image-generator
description	使用火山引擎（火山方舟）文本生成图像 API 生成高质量图片的技能。基于豆包 Seedream 系列模型， 支持文生图、多尺寸输出、批量生成，内置精细化成本管理和指数退避重试机制。 当用户需要：AI 绘图、文生图、生成图片、图像生成、调用火山引擎/豆包绘图 API、 创建图片生成脚本、批量出图、控制生图成本时，必须使用此 skill。 适用于需要对接火山方舟图像 API 的任何场景，无论用户说的是"画图"、"生成图像" 还是"调用火山 API 生图"，都应触发此 skill。
compatibility	{"python":">=3.8","dependencies":["requests>=2.28.0","openai>=1.0.0","volcengine-python-sdk"]}

🌋 火山引擎图像生成 Skill

快速概览

本 Skill 封装了火山方舟（Volcano Ark）图像生成 API，核心能力：

• 文生图：调用 doubao-seedream-4.0 / doubao-seedream-3.0 系列模型
• 成本管控：每次调用前预估费用，超预算自动降级模型/尺寸
• 容错重试：指数退避 + 抖动策略，区分可重试 / 不可重试错误
• 用量追踪：本地 JSON 记录每次调用的 token/图片消耗与花费

---

目录结构

volcano-image-generator/
├── SKILL.md                  # 本文件
├── config.example.json       # 配置模板（复制为 config.json 并填入密钥）
└── scripts/
    ├── generate_image.py     # 主生成脚本（CLI 入口）
    ├── volcano_signer.py     # API 认证与签名封装
    └── cost_manager.py       # 成本管理模块

---

工作流程

当被触发时，按如下顺序工作：

1. 读取配置 → config.json（从 config.example.json 复制并填写）
2. 成本预检 → cost_manager.py 评估预算，自动选择最优模型/尺寸
3. 签名认证 → volcano_signer.py 封装 Bearer Token 头
4. 调用 API → generate_image.py 发送请求，处理响应
5. 重试机制 → 失败时指数退避重试（最多 3 次）
6. 结果保存 → 下载图片到本地，更新成本日志

---

API 核心参数

参数	说明	示例值
model	模型 ID	doubao-seedream-4-0-250828
prompt	提示词（支持中英文）	"一只猫坐在夕阳下"
size	图片尺寸	"1024x1024" / "2K" / "4K"
response_format	返回格式	"url" 或 "b64_json"
n	批量生成数量	1~4
watermark	是否加水印	false
seed	随机种子（可复现）	-1
guidance_scale	提示词引导强度	7.5

API Endpoint: https://ark.cn-beijing.volces.com/api/v3/images/generations

---

模型与定价参考

模型	尺寸	参考价格/张	适用场景
doubao-seedream-3-0-t2i-250415	1024×1024	~¥0.12	日常生图，性价比高
doubao-seedream-4-0-250828	1024×1024	~¥0.20	高质量，商业场景
doubao-seedream-4-0-250828	2K	~¥0.35	高清输出
doubao-seedream-4-0-250828	4K	~¥0.60	超高清，海报/印刷

价格以火山引擎官方控制台公示为准，此处仅供参考。

---

快速使用

1. 配置

cd volcano-image-generator
cp config.example.json config.json
# 编辑 config.json，填入 ARK_API_KEY

2. 单张生图

python scripts/generate_image.py \
  --prompt "星空下的雪山，超写实风格" \
  --size 1024x1024 \
  --output ./output/

3. 批量生图（成本限制）

python scripts/generate_image.py \
  --prompt "赛博朋克城市夜景" \
  --n 4 \
  --budget 2.0 \   # 总预算上限（元）
  --output ./output/

4. 查看成本报告

python scripts/cost_manager.py --report

---

成本管理策略

cost_manager.py 实现以下策略：

• 预算门控：调用前检查 daily_limit / per_call_limit
• 模型降级：超预算时自动降级（4K→2K→1024）
• 累计追踪：cost_log.json 记录每日/每月用量
• 告警阈值：达到 80% 预算时打印警告

---

重试策略

generate_image.py 内置指数退避重试：

第1次失败 → 等待 1s 重试
第2次失败 → 等待 2s 重试  
第3次失败 → 等待 4s 重试
第3次仍失败 → 抛出最终异常

可重试错误：429 限流、502/503/504 服务暂时不可用、网络超时 不可重试错误：401 认证失败、400 参数错误、内容安全拦截

---

详细参考文件

• 脚本实现：scripts/generate_image.py — 主逻辑，含重试
• 认证封装：scripts/volcano_signer.py — API Key 管理
• 成本模块：scripts/cost_manager.py — 预算/追踪/降级
• 配置样例：config.example.json — 所有可配置项说明