# Volcano Image Generator

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

- Skill: `keluojun/volcano-image-generator` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add keluojun/volcano-image-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/keluojun/volcano-image-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: KeLuoJun (https://skillmd.com/u/keluojun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/keluojun/volcano-image-generator

---


# 🌋 火山引擎图像生成 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. 配置

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

### 2. 单张生图

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

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

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

### 4. 查看成本报告

```bash
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` — 所有可配置项说明