ark-image-gen

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: 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）

"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/              本地备用输出