# Ark Image Gen

> 火山方舟（Volcengine Ark）图片生成 Skill。支持文生图（t2i）和图片编辑（i2i），调用 Doubao Seedream / SeedEdit 系列模型。支持自然语言调用、模型 fallback、预算控制、失败重试队列。触发关键词：文生图、图片生成、图片编辑、生成图片、生成一张、画一张、画图、帮我画、帮我生成、ark image、seedream、seededit、t2i、i2i、火山方舟图片、批量生图、批量生成图片、图片风格模板。

- Skill: `pixiesgeosun/ark-image-gen` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add pixiesgeosun/ark-image-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pixiesgeosun/ark-image-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pixiesgeosun (https://skillmd.com/u/pixiesgeosun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pixiesgeosun/ark-image-gen

---


# ark-image-gen

火山方舟（Volcengine Ark）图片生成 Skill。支持文生图（t2i）和图片编辑（i2i），调用 Doubao Seedream / SeedEdit 系列模型。支持自然语言调用、模型 fallback、预算控制、失败重试队列。

## Setup

### 依赖
```bash
pip3 install 'volcengine-python-sdk[ark]' --break-system-packages
```

### API Key 配置
```bash
export ARK_API_KEY="YOUR_ARK_API_KEY"
```

## 自然语言调用规则（必读）

当用户用自然语言请求图片生成时，**直接调用本 Skill**，无需用户提供参数名称。

### 参数提取规则

| 用户说的 | 映射到 |
|---------|--------|
| "画一张..."、"生成一张..."、"帮我画..." | `generate --prompt` |
| "编辑这张图"、"修改图片"、"改成..." + 附带图片 | `edit --prompt --image` |
| "用 seedream 3.0"、"用最便宜的模型"、"3.0" | `--model seedream-3.0` |
| "用 4.5"、"用最新的"、"质量最好的" | `--model seedream-4.5` |
| "横版"、"4比3"、"4:3"、"横向" | `--size 4:3` → 1024×768 |
| "宽屏"、"16:9"、"16比9" | `--size 16:9` → 1024×576 |
| "电影比例"、"21:9"、"超宽屏" | `--size 21:9` → 1024×439 |
| "竖版"、"9:16"、"手机壁纸"、"海报"、"竖向" | `--size 9:16` → 576×1024 |
| "3比4"、"3:4" | `--size 3:4` → 768×1024 |
| "正方形"、"1:1"、"方形" | `--size 1:1` → 1024×1024 |
| "2K" | `--size 2K` → 2048×2048 |
| "4K" | `--size 4K` → 4096×4096 |
| "水墨画风格"、"吉卜力风格"、"赛博朋克" | `--style 水墨画/吉卜力/赛博朋克` |
| "生成 3 张"、"要 4 张"、"来四张" | `--n 3/4` |
| "不要出现人"、"避免模糊" | `--negative-prompt "..."` |
| "固定种子 42"、"用 seed 1234" | `--seed 42/1234` |

### 典型自然语言示例

> "帮我画一张水墨风的古城夜景，横版"
```bash
python3 SKILL_DIR/ark_image.py generate \
  --prompt "古城夜景" --style 水墨画 --size 16:9
```

> "生成 4 张儿童绘本风格的小兔子图片"
```bash
python3 SKILL_DIR/ark_image.py generate \
  --prompt "小兔子" --style 儿童绘本 --n 4
```

> "用最便宜的模型画一张赛博朋克城市"
```bash
python3 SKILL_DIR/ark_image.py generate \
  --prompt "赛博朋克城市" --model seedream-3.0
```

> "把这张图改成夜晚场景 [附图]"
```bash
python3 SKILL_DIR/ark_image.py edit \
  --prompt "改成夜晚场景" --image <图片URL或路径>
```

> "看看今天花了多少钱"
```bash
python3 SKILL_DIR/ark_image.py cost-report
```

> "重试失败的任务"
```bash
python3 SKILL_DIR/ark_image.py retry
```

## 执行方式

```python
import os, subprocess, re
skill_dir = os.path.expanduser("~/.agents/skills/ark-image-gen")
script = os.path.join(skill_dir, "ark_image.py")
env = os.environ.copy()
env["ARK_API_KEY"] = "YOUR_ARK_API_KEY"

result = subprocess.run(
    ["python3", script] + cmd_args,
    env=env, capture_output=True, text=True, timeout=180
)
print(result.stdout)
```

## ⚡ 图片发送规则（强制执行）

图片生成完成后，**必须调用 `message` tool 发送图片**，绝对不能只输出文件名或路径。

### 发送流程（两步，缺一不可）

**第一步：用 `exec` tool 获取 base64**

从脚本 stdout 的 `ARK_OUTPUT_FILES:` 段落拿到图片路径（例如 `/path/to/ark_xxx.png`），然后用 `exec` tool 执行：
```bash
base64 < /path/to/ark_xxx.png
```
拿到 base64 字符串。

**第二步：用 `message` tool 发送图片**

立刻调用 `message` tool，参数如下：
- `action`: `send`
- `channel`: `feishu`
- `message`: `✅ 图片已生成`（或简短描述）
- `buffer`: `data:image/png;base64,<上一步得到的base64字符串>`
- **不加 `target`**（OpenClaw 自动路由到当前对话，私聊/群聊均适用）

### 多张图片时

对每张图片分别执行上述两步（exec 读取 → message 发送），逐张发送。

### ❌ 禁止行为

- 禁止只输出文件名（如 `ark_20260407_xxx.png`）
- 禁止只输出文件路径
- 禁止用 `filePath` 参数（那只会发文本链接，不是图片）
- 禁止用任何内置飞书 API 发图（cross-app 限制，会导致 coordinator/writer/reviewer/群聊 发送失败）
- 禁止加 `target` 参数（会发到错误对话）
- **统一使用 message tool + buffer(base64)，所有 agent 私聊/群聊均适用**

## 模型选择策略

| 场景 | 推荐模型 |
|------|---------|
| 默认 / 日常使用 | seedream-3.0（最低价）|
| 额度耗尽时自动 fallback | seedream-4.5 |
| 用户明确要求高质量 | seedream-4.5 |
| 图片编辑（i2i）| seededit-3.0 |

## 预算控制配置（models.json）

```json
"budget": {
  "enabled": true,
  "daily_limit_cny": 10.0,       // 每日上限（元）
  "single_job_limit_cny": 2.0,   // 单次任务上限（元）
  "warn_threshold_cny": 8.0,     // 达到此值时发出警告
  "block_on_exceed": true        // true=超限阻断，false=仅警告
}
```

**建议预算（每日上限 ¥10）：**
- seedream-3.0 @ ¥0.04/张 → 最多 250 张/天
- seedream-4.5 @ ¥0.10/张 → 最多 100 张/天
- 单次 ¥2 上限 → 最多 50 张/次（3.0）或 20 张/次（4.5）

## 失败重试队列

- 所有 API 错误（网络、超时）自动入队 `output/retry_queue.jsonl`
- 每个任务最多重试 5 次后放弃
- 用 `retry` 命令手动触发执行

## 输出路径

- iCloud：`~/Library/Mobile Documents/com~apple~CloudDocs/Openclaw Workspace/ark-images/`
- 本地备用：`~/.agents/skills/ark-image-gen/output/images/`

## Files

```
~/.agents/skills/ark-image-gen/
├── SKILL.md
├── ark_image.py
├── models.json              模型配置 + 预算配置
├── styles/templates.json    风格模板库
└── output/
    ├── costs.jsonl          成本记录
    ├── retry_queue.jsonl    失败重试队列
    └── images/              本地备用输出
```