Ark Image Gen

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，无需用户提供参数名称。

参数提取规则

典型自然语言示例

"帮我画一张水墨风的古城夜景，横版"

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 私聊/群聊均适用

模型选择策略

预算控制配置（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/              本地备用输出