| name | ark-image-gen |
| version | 1.0.0 |
| description | 火山方舟（Volcengine Ark）图片生成 Skill。支持文生图（t2i）和图片编辑（i2i），调用 Doubao Seedream / SeedEdit 系列模型。支持自然语言调用、模型 fallback、预算控制、失败重试队列。触发关键词：文生图、图片生成、图片编辑、生成图片、生成一张、画一张、画图、帮我画、帮我生成、ark image、seedream、seededit、t2i、i2i、火山方舟图片、批量生图、批量生成图片、图片风格模板。 |
| metadata | {"requires":{"bins":["python3"],"env":["ARK_API_KEY"]}} |
ark-image-gen
火山方舟（Volcengine Ark）图片生成 Skill。支持文生图（t2i）和图片编辑（i2i），调用 Doubao Seedream / SeedEdit 系列模型。支持自然语言调用、模型 fallback、预算控制、失败重试队列。
Setup
依赖
pip3 install 'volcengine-python-sdk[ark]' --break-system-packages
API Key 配置
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 |
典型自然语言示例
"帮我画一张水墨风的古城夜景，横版"
python3 SKILL_DIR/ark_image.py generate \
--prompt "古城夜景" --style 水墨画 --size 16:9
"生成 4 张儿童绘本风格的小兔子图片"
python3 SKILL_DIR/ark_image.py generate \
--prompt "小兔子" --style 儿童绘本 --n 4
"用最便宜的模型画一张赛博朋克城市"
python3 SKILL_DIR/ark_image.py generate \
--prompt "赛博朋克城市" --model seedream-3.0
"把这张图改成夜晚场景 [附图]"
python3 SKILL_DIR/ark_image.py edit \
--prompt "改成夜晚场景" --image <图片URL或路径>
"看看今天花了多少钱"
python3 SKILL_DIR/ark_image.py cost-report
"重试失败的任务"
python3 SKILL_DIR/ark_image.py retry
执行方式
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 执行：
base64 < /path/to/ark_xxx.png
拿到 base64 字符串。
第二步：用 message tool 发送图片
立刻调用 message tool，参数如下：
action: sendchannel: feishumessage: ✅ 图片已生成（或简短描述）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）
"budget": {
"enabled": true,
"daily_limit_cny": 10.0,
"single_job_limit_cny": 2.0,
"warn_threshold_cny": 8.0,
"block_on_exceed": true
}
建议预算（每日上限 ¥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/ 本地备用输出
