实战：将 agnes-image 从 2.1 升级到 2.5 Flash

最近一次 OpenClaw 技能迭代中，我们完成了 agnes-image skill 从 2.1 Flash 到 2.5 Flash 的版本升级。这是一次比较典型的"官方 API 大版本更新 → skill 同步跟进"的维护场景。下面把这个过程完整记录一下，方便后续参考。

升级起因

事情开始于一个简单的问题：用户问「当前模型是什么版本？」

我们习惯性地读了 SKILL.md 和脚本，发现模型名还是旧的 agnes-image-2.1-flash。用户随即甩来一个链接：https://www.agnes-ai.com/zh-Hans/docs/agnes-image-25-flash，说应该升级到 2.5 了。

这个场景其实很常见——模型提供商发布新版本后，我们的 skill 文档和脚本往往滞后。及时跟进不是可选项，是必须的。

官方文档关键变更

拉取官方文档后，提炼出以下核心变化：

1. 模型名称变更

最直接的变化：

# 旧
model: "agnes-image-2.1-flash"

# 新
model: "agnes-image-2.5-flash"

端点 URL 不变，还是 POST https://apihub.agnes-ai.com/v1/images/generations。

2. 新增档位尺寸（1K / 2K / 3K / 4K）

2.5 版本引入了一套更直观的档位系统：

当然，传统的像素尺寸写法（如 1024x768）仍然兼容。

3. 新增 ratio 宽高比参数

这是个很实用的新增功能。以前要控制比例只能靠猜像素组合，现在可以直接指定：

{
  "model": "agnes-image-2.5-flash",
  "size": "2K",
  "ratio": "16:9"
}

支持的 ratio 值：1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9。

4. image 参数从 extra_body 提升到顶层

这是最影响代码改动的地方。旧结构：

{
  "model": "agnes-image-2.1-flash",
  "prompt": "...",
  "extra_body": {
    "image": ["https://example.com/input.png"]
  }
}

新结构：

{
  "model": "agnes-image-2.5-flash",
  "prompt": "...",
  "image": ["https://example.com/input.png"]
}

image 从 extra_body 内部移到了请求体的顶层，和 prompt、size 平级。这对图生图和多图合成都更直观了。

5. 支持多图合成与 Base64 输出

2.5 版本支持传入多张图片进行合成（image 字段可以是多元素数组），同时新增了 return_base64 模式，可以通过 CLI 的 --response-format base64 参数启用。

我们改了哪些文件

本次升级涉及 4 个文件的同步修改：

文件 1：scripts/agnes_image.py

这是核心脚本，改动最多：

• 模型名：MODEL = "agnes-image-2.5-flash"
• 新增 --ratio 参数： argparse 中添加了 ratio 选项，校验 choices 为支持的宽高比列表
• image 提升到顶层：build_payload() 中 args.image_url 直接挂到 payload 顶层，不再塞进 extra_body
• 新增 --response-format base64：当指定 base64 时设置 payload["return_base64"] = True
• size 校验兼容档位：validate_size() 新增正则匹配 1K/2K/3K/4K 档位格式

关键代码片段：

MODEL = "agnes-image-2.5-flash"

SIZE_PATTERNS = [
    re.compile(r"^[1-9][0-9]{1,4}x[1-9][0-9]{1,4}$"),  # 传统像素
    re.compile(r"^(1K|2K|3K|4K)$"),                      # 档位
]

def build_payload(args):
    validate_size(args.size)
    payload = {"model": MODEL, "prompt": args.prompt, "size": args.size}
    if args.ratio:
        payload["ratio"] = args.ratio
    if args.image_url:
        payload["image"] = args.image_url          # 顶层，不再是 extra_body
    if args.response_format == "base64":
        payload["return_base64"] = True
    return payload

文件 2：SKILL.md

全文更新，主要包括：

• 标题和描述中的版本号更新
• API 信息表格中的模型名
• 请求参数表新增 ratio 字段说明
• 图生图示例改为顶层 image 结构
• 新增档位尺寸的说明
• 新增 --ratio 和 --response-format 的 CLI 用法说明
• 更新最佳实践中的尺寸推荐

文件 3：AGENTS.md

更新了模型名和新参数说明，让各 Agent 代理知道新 skill 的能力边界。

文件 4：MEMORY.md

修复了重复条目（2.1 和 2.5 并存导致的重复记录），更新了工具链描述。

验证：dry-run 测试

升级完成后，用 --dry-run 模式跑了 6 个用例，确认请求 JSON 结构正确：

所有用例的 payload 结构均符合 2.5 API 规范。以下是第 2 个用例的输出示例：

{
  "url": "https://apihub.agnes-ai.com/v1/images/generations",
  "payload": {
    "model": "agnes-image-2.5-flash",
    "prompt": "test prompt",
    "size": "2K",
    "ratio": "16:9"
  }
}

和第 4 个用例（图生图）的 payload：

{
  "url": "https://apihub.agnes-ai.com/v1/images/generations",
  "payload": {
    "model": "agnes-image-2.5-flash",
    "prompt": "test prompt",
    "size": "2K",
    "ratio": "3:2",
    "image": ["https://example.com/ref.png"]
  }
}

可以看到 image 已经在顶层了，ratio 也正确传递。

升级过程中的几个注意点

1. 文档滞后是常态

这次升级的触发点是用户主动提醒。实际工作中，API 提供商发布新版本后，我们往往不会第一时间知道。建议在 SKILL.md 中加一个 last_update 字段，定期核查官方文档，主动发现版本差异。

2. image 参数位置变化影响最大

这是最容易遗漏的 Breaking Change。旧代码中 extra_body["image"] 的写法在新版本下会直接报错（API 不认识这个嵌套路径）。升级后一定要检查所有调用方是否还在用旧结构。

3. 档位尺寸 vs 像素尺寸

2.5 版本同时支持两种尺寸写法。在实际使用中，档位尺寸 + ratio 的组合更可预期——API 会自动映射到最接近的标准分辨率。如果业务对精确像素有要求，还是用传统的 1600x900 写法更可控。

4. 向后兼容性

从实际测试来看，2.5 API 对旧参数结构有一定容忍度（extra_body 中的 image 可能仍被识别），但不建议依赖这种隐式兼容。该改的就改干净。

总结

这次升级从发现到完成，全过程大约 30 分钟：

1. 确认官方文档变更（5 分钟）
2. 修改脚本（10 分钟）
3. 更新 SKILL.md / AGENTS.md / MEMORY.md（10 分钟）
4. dry-run 验证（5 分钟）

核心改动其实不多，但涉及 4 个文件的同步更新，漏掉任何一个都会导致功能异常或文档不一致。skill 维护的价值就在于这种"小事不小"——一个模型名的变化，牵扯到脚本、文档、配置、记忆四处联动。

关联阅读

• [[OpenClaw skill 批量创建实录]]
• [[blog-pipeline HITL 事故复盘]]
• [[技能生态探索]]

参考来源

• Agnes Image 2.5 Flash 官方文档
• Agnes API Hub
• OpenClaw Skill 管理