| 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 # 成本管理模块
工作流程
当被触发时，按如下顺序工作：
- 读取配置 →
config.json（从 config.example.json 复制并填写）
- 成本预检 →
cost_manager.py 评估预算，自动选择最优模型/尺寸
- 签名认证 →
volcano_signer.py 封装 Bearer Token 头
- 调用 API →
generate_image.py 发送请求，处理响应
- 重试机制 → 失败时指数退避重试（最多 3 次）
- 结果保存 → 下载图片到本地，更新成本日志
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
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 — 所有可配置项说明
